modern-monaco 0.0.0-beta.5 → 0.1.1

package/README.md

@@ -1,20 +1,20 @@
 > [!WARNING]
-> **This project is currently under active development, the API may change at any time. Use at your own risk.**
+> **This project is currently under active development. The API may change at any time. Use at your own risk.**
 > Please report any issues or feature requests on the [issues](https://github.com/esm-dev/modern-monaco/issues) page.
 
 # Modern Monaco
 
-Meeting the modern version of [Monaco Editor](https://www.npmjs.com/package/monaco-editor):
+Meet the modern version of [Monaco Editor](https://www.npmjs.com/package/monaco-editor):
 
-- Easy to use, no `MonacoEnvironment` setup and web-worker/css loader needed.
-- Using [Shiki](https://shiki.style) for syntax highlighting with tons of grammars and themes.
-- Lazy loading: pre-highlighting code with Shiki while loading `monaco-editor-core` in background.
-- Support server-side rendering(SSR).
-- Workspace (edit history, file system provider, persist protocol, etc).
-- Automatically loading `.d.ts` from [esm.sh](https://esm.sh) CDN for type checking.
-- Using [import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) for resolving **bare specifier** imports in JavaScript/TypeScript.
+- Easy to use, no `MonacoEnvironment` setup, web workers, or CSS loaders required.
+- Uses [Shiki](https://shiki.style) for syntax highlighting with extensive grammars and themes.
+- Lazy loading: pre-highlight code with Shiki while loading `monaco-editor-core` in the background.
+- Supports server-side rendering (SSR).
+- Workspace features (edit history, file system provider, persist protocol, etc.).
+- Automatically loads `.d.ts` files from [esm.sh](https://esm.sh) CDN for type checking.
+- Uses [import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) for resolving **bare specifier** imports in JavaScript/TypeScript.
 - VSCode `window` APIs like `showInputBox`, `showQuickPick`, etc.
-- Embedded languages(importmap/CSS/JavaScript) in HTML.
+- Embedded languages (importmap/CSS/JavaScript) in HTML.
 - Inline `html` and `css` in JavaScript/TypeScript.
 - Auto-closing HTML/JSX tags.
 
@@ -27,9 +27,9 @@ npm i modern-monaco typescript
 ```
 
 > [!Note]
-> The `typescript` package is required by JavaScript/TypeScript LSP worker. We recommend `typescript@5.5.x` or later.
+> The `typescript` package is required by the JavaScript/TypeScript LSP worker. We recommend `typescript@5.5.x` or later.
 
-or import it from [esm.sh](https://esm.sh/) CDN in browser without build step:
+Or import it from [esm.sh](https://esm.sh/) CDN in the browser without a build step:
 
 ```js
 import * from "https://esm.sh/modern-monaco"
@@ -40,38 +40,46 @@ import * from "https://esm.sh/modern-monaco"
 `modern-monaco` provides three modes to create a browser-based code editor:
 
 - **Lazy**: pre-highlight code with Shiki while loading the `editor-core.js` in the background.
-- **SSR**: render a mock editor on the server side, and hydrate it on the client side.
-- **Manual**: create a monaco editor instance manually.
+- **SSR**: render a mock editor on the server side and hydrates it on the client side.
+- **Manual**: create a Monaco editor instance manually.
 
 ### Lazy Mode
 
-[monaco-editor](https://www.npmjs.com/package/monaco-editor) is a large package with extra CSS/Worker modules, and needs the `MonacoEnvironment` setup for language service support. `modern-monaco` provides a lazy but smart way to load the editor modules on demand.
+[monaco-editor](https://www.npmjs.com/package/monaco-editor) is a large package with additional CSS/Worker modules that requires `MonacoEnvironment` setup for language service support. `modern-monaco` provides a simple yet smart way to load editor modules on demand.
 
-By pre-highlighting code with Shiki while loading editor modules in the background, `modern-monaco` can reduce the loading screen time.
+By pre-highlighting code with Shiki while loading editor modules in the background, `modern-monaco` can significantly reduce loading screen time.
+
+To create a Monaco editor lazily, you need to add a `<monaco-editor>` custom element in your app's HTML, then call the `lazy` function from modern-monaco. You also need to provide a workspace object to manage files for the editor.
 
 ```html
+<!-- index.html -->
 <monaco-editor></monaco-editor>
+<script src="app.js" type="module"></script>
+```
 
-<script type="module">
-  import { lazy, Workspace } from "modern-monaco";
+```js
+// app.js
+import { lazy, Workspace } from "modern-monaco";
 
-  // create a workspace with initial files
-  const workspace = new Workspace({
-    initialFiles: {
-      "index.html": `<html><head><title>Hello, world!</title></head><body><script src="main.js"></script></body></html>`,
-      "main.js": `console.log("Hello, world!")`
-    },
-    entryFile: "index.html",
-  });
+// create a workspace with initial files
+const workspace = new Workspace({
+  initialFiles: {
+    "index.html": `<html>...</body></html>`,
+    "main.js": `console.log("Hello, world!")`
+  },
+  entryFile: "index.html",
+});
 
-  // initialize the editor lazily
-  lazy({ workspace });
-</script>
+// initialize the editor lazily
+await lazy({ workspace });
+
+// open a file in the workspace
+workspace.openTextDocument("main.js");
 ```
 
 ### SSR Mode
 
-SSR mode returns an instant pre-rendered editor on the server side, and hydrate it on the client side.
+SSR mode returns an instant pre-rendered editor on the server side and hydrates it on the client side.
 
 ```js
 import { renderToWebComponent } from "modern-monaco/ssr";
@@ -103,7 +111,7 @@ export default {
 
 ### Manual Mode
 
-You can also create a [monaco editor](https://microsoft.github.io/monaco-editor/docs.html) instance manually.
+You can also create a [Monaco editor](https://microsoft.github.io/monaco-editor/docs.html) instance manually. It loads themes and language grammars automatically.
 
 ```html
 <div id="editor"></div>
@@ -114,7 +122,7 @@ You can also create a [monaco editor](https://microsoft.github.io/monaco-editor/
   // load monaco-editor-core.js
   const monaco = await init();
 
-  // create a monaco editor instance
+  // create a Monaco editor instance
   const editor = monaco.editor.create(document.getElementById("editor"));
 
   // create and attach a model to the editor
@@ -124,21 +132,21 @@ You can also create a [monaco editor](https://microsoft.github.io/monaco-editor/
 
 ## Using Workspace
 
-`modern-monaco` provides VSCode-like workspace features, like edit history, file system provider, etc.
+`modern-monaco` provides VSCode-like workspace features, such as edit history, file system provider, and more.
 
 ```js
 import { lazy, Workspace } from "modern-monaco";
 
 // 1. create a workspace with initial files
 const workspace = new Workspace({
-  /** the name of the workspace, used for project isolation, default is "default". */
+  /** The name of the workspace, used for project isolation. Default is "default". */
   name: "project-name",
-  /** initial files in the workspace. */
+  /** Initial files in the workspace. */
   initialFiles: {
     "index.html": `<html><head><title>Hello, world!</title></head><body><script src="main.js"></script></body></html>`,
     "main.js": `console.log("Hello, world!")`,
   },
-  /** file to open when the editor is loaded for the first time. */
+  /** File to open when the editor is loaded for the first time. */
   entryFile: "index.html",
 });
 
@@ -205,7 +213,7 @@ const workspace = new Workspace({
 });
 ```
 
-You can also provide an importmap object as the `lsp.typescript.importMap` option in the `lazy`, `init`, or `hydrate` function.
+You can also provide an import map object as the `lsp.typescript.importMap` option in the `lazy`, `init`, or `hydrate` functions.
 
 ```js
 lazy({
@@ -221,22 +229,42 @@ lazy({
 ```
 
 > [!Note]
-> By default, `modern-monaco` uses `react` or `preact` in the `importmap` script as the `jsxImportSource` option for typescript worker.
-> To use a custom `jsxImportSource` option, add `@jsxRuntime` specifier in the `importmap` script.
+> By default, `modern-monaco` uses `react` or `preact` in the `importmap` script as the `jsxImportSource` option for the TypeScript worker.
+> To use a custom `jsxImportSource` option, add the `@jsxRuntime` specifier in the `importmap` script.
+
+### Using Custom FileSystem
+
+You can provide a custom filesystem implementation to override the default IndexedDB filesystem.
+
+```ts
+import { lazy, type FileSystem, Workspace } from "modern-monaco";
+
+class CustomFileSystem implements FileSystem {
+  // Custom FileSystem implementation
+}
+
+const workspace = new Workspace({
+  initialFiles: {
+    "index.html": indexHtml,
+    "app.tsx": appTsx,
+  },
+  customFs: new CustomFileSystem(),
+});
+```
 
 ## Editor Theme & Language Grammars
 
-`modern-monaco` uses [Shiki](https://shiki.style) for syntax highlighting with tons of grammars and themes. By default, it loads themes and grammars from esm.sh on demand.
+`modern-monaco` uses [Shiki](https://shiki.style) for syntax highlighting with extensive grammars and themes. By default, it loads themes and grammars from esm.sh on demand.
 
 ### Setting the Editor Theme
 
-To set the theme of the editor, you can add a `theme` attribute to the `<monaco-editor>` element.
+To set the editor theme, you can add a `theme` attribute to the `<monaco-editor>` element.
 
 ```html
 <monaco-editor theme="OneDark-Pro"></monaco-editor>
 ```
 
-or set it in the `lazy`, `init`, or `hydrate` function.
+Or set it in the `lazy`, `init`, or `hydrate` function.
 
 ```js
 lazy({
@@ -253,13 +281,13 @@ lazy({
 import OneDark from "tm-themes/themes/OneDark-Pro.json" with { type: "json" };
 
 lazy({
-  theme: OneDark
+  theme: OneDark,
 });
 ```
 
 ### Pre-loading Language Grammars
 
-By default, `modern-monaco` loads language grammars when a specific language mode is attached in the editor. You can also pre-load language grammars by adding the `langs` option to the `lazy`, `init`, or `hydrate` function. The `langs` option is an array of language grammars, which can be a language grammar object, a language ID, or a URL to the language grammar.
+By default, `modern-monaco` loads language grammars when a specific language mode is attached to the editor. You can also pre-load language grammars by adding the `langs` option to the `lazy`, `init`, or `hydrate` functions. The `langs` option is an array of language grammars, which can be a language grammar object, a language ID, or a URL to the language grammar.
 
 ```js
 import markdown from "tm-grammars/markdown.json" with { type: "json" };
@@ -278,7 +306,7 @@ lazy({
     // load language grammar from a local file
     "/assets/mylang.json",
 
-    // use `tm-grammars` package without extra http requests, but increases the bundle size
+    // use `tm-grammars` package without extra HTTP requests, but increases the bundle size
     markdown,
 
     // dynamically import
@@ -291,14 +319,14 @@ lazy({
       patterns: [/* ... */],
     },
   ],
-  // the CDN for loading language grammars and themes, default is "https://esm.sh"
-  tmDownloadCDN: "https://unpkg.com",
+  // The CDN for loading language grammars and themes. Default is "https://esm.sh"
+  tmDownloadCDN: "https://esm.sh",
 });
 ```
 
 ## Editor Options
 
-You can set the editor options in the `<monaco-editor>` element as attributes. The editor options are the same as the [`editor.EditorOptions`](https://microsoft.github.io/monaco-editor/docs.html#variables/editor.EditorOptions.html).
+You can set editor options as attributes in the `<monaco-editor>` element. The editor options are the same as [`editor.EditorOptions`](https://microsoft.github.io/monaco-editor/docs.html#variables/editor.EditorOptions.html).
 
 ```html
 <monaco-editor
@@ -308,7 +336,7 @@ You can set the editor options in the `<monaco-editor>` element as attributes. T
 ></monaco-editor>
 ```
 
-For SSR mode, you can set the editor options in the `renderToWebComponent` function.
+For SSR mode, you can set editor options in the `renderToWebComponent` function.
 
 ```js
 import { renderToWebComponent } from "modern-monaco/ssr";
@@ -335,20 +363,20 @@ For manual mode, check [here](https://microsoft.github.io/monaco-editor/docs.htm
 - JavaScript/TypeScript
 - JSON
 
-Plus, `modern-monaco` also supports features like:
+Additionally, `modern-monaco` supports features like:
 
 - File System Provider for import completions
 - Embedded languages in HTML
-- Inline `html` and `css` in JavaScript/TypeScript.
+- Inline `html` and `css` in JavaScript/TypeScript
 - Auto-closing HTML/JSX tags
 
 > [!Note]
-> You don't need to set the `MonacoEnvironment.getWorker` for LSP support.
-> `modern-monaco` will automatically load the required LSP workers.
+> You don't need to set `MonacoEnvironment.getWorker` for LSP support.
+> `modern-monaco` automatically loads the required LSP workers.
 
-### LSP language configuration
+### LSP Language Configuration
 
-You can configure built-in LSPs in the `lazy`, `init`, or `hydrate` function.
+You can configure built-in LSPs in the `lazy`, `init`, or `hydrate` functions.
 
 ```js
 lazy({
@@ -386,7 +414,7 @@ export interface LSPLanguageConfig {
 }
 ```
 
-## Using `core` module
+## Using the `core` Module
 
 `modern-monaco` includes built-in grammars and LSP providers for HTML, CSS, JavaScript/TypeScript, and JSON. If you don't need these features, you can use the `modern-monaco/core` sub-module to reduce the bundle size.
 

package/dist/core.js

@@ -91,25 +91,15 @@ async function init(options) {
   return loadMonaco(hightlighter, options?.workspace, options?.lsp);
 }
 async function lazy(options, hydrate2) {
-  const workspace = options?.workspace;
   const { promise: editorWorkerPromise, resolve: onDidEditorWorkerResolve } = promiseWithResolvers();
-  let monacoCore = null;
-  function load(highlighter) {
-    if (monacoCore) {
-      return monacoCore;
-    }
-    return monacoCore = loadMonaco(highlighter, workspace, options?.lsp, onDidEditorWorkerResolve).then((m) => monacoCore = m);
-  }
-  function setStyle(el, style) {
-    Object.assign(el.style, style);
-  }
-  function getAttr(el, name) {
-    return el.getAttribute(name);
-  }
+  const getAttr = (el, name) => el.getAttribute(name);
+  const setStyle = (el, style) => Object.assign(el.style, style);
+  let monacoPromise = null;
   customElements.define(
     "monaco-editor",
     class extends HTMLElement {
       async connectedCallback() {
+        const workspace = options?.workspace;
         const renderOptions = {};
         for (const attrName of this.getAttributeNames()) {
           const key = editorProps.find((k) => k.toLowerCase() === attrName);
@@ -261,7 +251,7 @@ async function lazy(options, hydrate2) {
           }
         }
         async function createEditor() {
-          const monaco = await load(highlighter);
+          const monaco = await (monacoPromise ?? (monacoPromise = loadMonaco(highlighter, workspace, options?.lsp, onDidEditorWorkerResolve)));
           const editor = monaco.editor.create(containerEl, renderOptions);
           if (workspace) {
             const storeViewState = () => {
@@ -324,9 +314,6 @@ async function lazy(options, hydrate2) {
     }
   );
   await editorWorkerPromise;
-  return {
-    workspace
-  };
 }
 function hydrate(options) {
   return lazy(options, true);

package/dist/index.js

@@ -715,7 +715,7 @@ var builtinLSPProviders = {
   }
 };
 
-// node_modules/.pnpm/tm-grammars@1.24.1/node_modules/tm-grammars/grammars/html.json
+// node_modules/.pnpm/tm-grammars@1.24.3/node_modules/tm-grammars/grammars/html.json
 var html_default = {
   displayName: "HTML",
   injections: {
@@ -3344,7 +3344,7 @@ var html_default = {
   scopeName: "text.html.basic"
 };
 
-// node_modules/.pnpm/tm-grammars@1.24.1/node_modules/tm-grammars/grammars/css.json
+// node_modules/.pnpm/tm-grammars@1.24.3/node_modules/tm-grammars/grammars/css.json
 var css_default = {
   displayName: "CSS",
   name: "css",
@@ -5206,7 +5206,7 @@ var css_default = {
   scopeName: "source.css"
 };
 
-// node_modules/.pnpm/tm-grammars@1.24.1/node_modules/tm-grammars/grammars/javascript.json
+// node_modules/.pnpm/tm-grammars@1.24.3/node_modules/tm-grammars/grammars/javascript.json
 var javascript_default = {
   displayName: "JavaScript",
   name: "javascript",
@@ -11204,7 +11204,7 @@ var javascript_default = {
   scopeName: "source.js"
 };
 
-// node_modules/.pnpm/tm-grammars@1.24.1/node_modules/tm-grammars/grammars/typescript.json
+// node_modules/.pnpm/tm-grammars@1.24.3/node_modules/tm-grammars/grammars/typescript.json
 var typescript_default = {
   displayName: "TypeScript",
   name: "typescript",
@@ -16953,7 +16953,7 @@ var typescript_default = {
   scopeName: "source.ts"
 };
 
-// node_modules/.pnpm/tm-grammars@1.24.1/node_modules/tm-grammars/grammars/jsx.json
+// node_modules/.pnpm/tm-grammars@1.24.3/node_modules/tm-grammars/grammars/jsx.json
 var jsx_default = {
   displayName: "JSX",
   name: "jsx",
@@ -22951,7 +22951,7 @@ var jsx_default = {
   scopeName: "source.js.jsx"
 };
 
-// node_modules/.pnpm/tm-grammars@1.24.1/node_modules/tm-grammars/grammars/tsx.json
+// node_modules/.pnpm/tm-grammars@1.24.3/node_modules/tm-grammars/grammars/tsx.json
 var tsx_default = {
   displayName: "TSX",
   name: "tsx",
@@ -28949,7 +28949,7 @@ var tsx_default = {
   scopeName: "source.tsx"
 };
 
-// node_modules/.pnpm/tm-grammars@1.24.1/node_modules/tm-grammars/grammars/json.json
+// node_modules/.pnpm/tm-grammars@1.24.3/node_modules/tm-grammars/grammars/json.json
 var json_default = {
   displayName: "JSON",
   name: "json",