modern-monaco 0.0.0-beta.0 → 0.0.0-beta.2

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020-2024 Je Xia <i@jex.me>
+Copyright (c) 2025 Je Xia <i@jex.me>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,37 +1,26 @@
 > [!WARNING]
-> **This project is currently under active development and is not ready for production use.**
+> **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):
 
-- Easy to use, no `MonacoEnvironment` setup and web-worker/css loader
+- 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, etc).
+- 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://github.com/WICG/import-maps) for resolving **bare specifier** imports in JavaScript/TypeScript.
+- Using [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.
 - Inline `html` and `css` in JavaScript/TypeScript.
 - Auto-closing HTML/JSX tags.
 
-Planned features:
-
-- [ ] Show a loading indicator while loading the editor
-- [ ] Quick open menu (only if a workspace is provided)
-- [ ] Drag and drop file (only if a workspace is provided)
-- [ ] Display non-code files, like images, videos, etc
-- [ ] VSCode `winodow.show<XXX>Message` APIs
-- [ ] Emmet
-- [ ] Markdown language service
-- [ ] [Volar](https://github.com/volarjs/volar.js) integration
-- [ ] Support [Shiki JS RegExp Engine](https://shiki.style/guide/regex-engines#javascript-regexp-engine-experimental)
-
 ## Installation
 
-You can install the package from NPM in your node project with a bundler like [vite](http://vitejs.dev).
+You can install `modern-monaco` from NPM:
 
 ```bash
 npm i modern-monaco typescript
@@ -40,7 +29,7 @@ npm i modern-monaco typescript
 > [!Note]
 > The `typescript` package is required by JavaScript/TypeScript LSP worker. We recommend `typescript@5.5.x` or later.
 
-or import it from [esm.sh](https://esm.sh/) in browser without build step:
+or import it from [esm.sh](https://esm.sh/) CDN in browser without build step:
 
 ```js
 import * from "https://esm.sh/modern-monaco"
@@ -48,15 +37,17 @@ import * from "https://esm.sh/modern-monaco"
 
 ## Usage
 
-`modern-monaco` provides three modes to create a browser based code editor:
+`modern-monaco` provides three modes to create a browser-based code editor:
 
-- **Lazy**: pre-hightlight code with Shiki while loading the `editor-core.js` in background.
-- **SSR**: render the editor in server side, and hydrate it in client side.
+- **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.
 
 ### Lazy Mode
 
-[monaco-editor](https://www.npmjs.com/package/monaco-editor) is a large package with extra CSS/Worker dependencies, not mention the `MonacoEnvironment` setup. `modern-monaco` provides a lazy but smart way to load the editor on demand, and it pre-highlights code with Shiki while loading the `editor-core.js` in background.
+[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.
+
+By pre-highlighting code with Shiki while loading editor modules in the background, `modern-monaco` can reduce the loading screen time.
 
 ```html
 <monaco-editor></monaco-editor>
@@ -80,29 +71,34 @@ import * from "https://esm.sh/modern-monaco"
 
 ### SSR Mode
 
-SSR mode returns a instant rendered editor in server side, and hydrate it in client side.
+SSR mode returns an instant pre-rendered editor on the server side, and hydrate it on the client side.
 
 ```js
 import { renderToWebComponent } from "modern-monaco/ssr";
 
 export default {
-  fetch(req) => {
-    const ssrOut = renderToWebComponent({
-      filename: "main.js",
-      code: `console.log("Hello, world!")`,
-      userAgent: req.headers.get("user-agent"), // detecte default font for different platforms
-      theme: "theme-id",
-    });
-    return new Response(html`
+  async fetch(req) {
+    const ssrOut = await renderToWebComponent(
+      `console.log("Hello, world!")`,
+      {
+        theme: "OneDark-Pro",
+        language: "javascript",
+        userAgent: req.headers.get("user-agent"), // detect default font for different platforms
+      },
+    );
+    return new Response(
+      html`
       ${ssrOut}
       <script type="module">
         import { hydrate } from "https://esm.sh/modern-monaco";
         // hydrate the editor
         hydrate();
       </script>
-    `, { headers: { "Content-Type": "text/html" }});
-  }
-}
+    `,
+      { headers: { "Content-Type": "text/html" } },
+    );
+  },
+};
 ```
 
 ### Manual Mode
@@ -128,7 +124,7 @@ 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, like edit history, file system provider, etc.
 
 ```js
 import { lazy, Workspace } from "modern-monaco";
@@ -142,7 +138,7 @@ const workspace = new Workspace({
     "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 at first time. */
+  /** file to open when the editor is loaded for the first time. */
   entryFile: "index.html",
 });
 
@@ -150,12 +146,12 @@ const workspace = new Workspace({
 lazy({ workspace });
 
 // 3. open a file in the workspace
-workspace.openTextDocument("main.js")
+workspace.openTextDocument("main.js");
 ```
 
 ### Adding `tsconfig.json`
 
-You can also add a `tsconfig.json` file to configure the TypeScript compiler options for the TypeScript language service worker.
+You can add a `tsconfig.json` file to configure the TypeScript compiler options for the TypeScript language service.
 
 ```js
 const tsconfig = {
@@ -175,8 +171,7 @@ const workspace = new Workspace({
 
 ### Using Import Maps
 
-`modern-monaco` uses [import maps](https://github.com/WICG/import-maps) to resolving **bare specifier** import in JavaScript/TypeScript.
-By default, `modern-monaco` dedetects the `importmap` script of root `index.html`.
+`modern-monaco` uses [import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to resolve **bare specifier** imports in JavaScript/TypeScript. By default, `modern-monaco` detects the `importmap` from the root `index.html` in the workspace.
 
 ```js
 const indexHtml = html`<!DOCTYPE html>
@@ -185,80 +180,119 @@ const indexHtml = html`<!DOCTYPE html>
     <script type="importmap">
       {
         "imports": {
-          "@jsxRuntime": "https://esm.sh/react@18",
-          "react": "https://esm.sh/react@18"
+          "react": "https://esm.sh/react@18",
+          "react-dom/": "https://esm.sh/react-dom@18/"
         }
       }
     </script>
   </head>
   <body>
-    <script type="module">
-      import React from "react";
-    </script>
+    <div id="root"></div>
+    <script type="module" src="app.tsx"></script>
   </body>
 </html>
 `;
+const appTsx = `import { createRoot } from "react-dom/client";
+
+createRoot(document.getElementById("root")).render(<div>Hello, world!</div>);
+`;
+
 const workspace = new Workspace({
   initialFiles: {
     "index.html": indexHtml,
+    "app.tsx": appTsx,
+  },
+});
+```
+
+You can also provide an importmap object as the `lsp.typescript.importMap` option in the `lazy`, `init`, or `hydrate` function.
+
+```js
+lazy({
+  lsp: {
+    typescript: {
+      importMap: {
+        "react": "https://esm.sh/react@18",
+        "react-dom/": "https://esm.sh/react-dom@18/",
+      },
+    },
   },
 });
 ```
 
 > [!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. For example, [solid-js](https://esm.sh/solid-js/jsx-runtime).
-
+> To use a custom `jsxImportSource` option, add `@jsxRuntime` specifier in the `importmap` script.
 
 ## Editor Theme & Language Grammars
 
-`modern-monaco` uses [Shiki](https://shiki.style) for syntax highlighting with tons of grammars and themes. It loads themes and grammars from esm.sh on demand.
+`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.
 
 ### Setting the Editor Theme
 
 To set the theme of the editor, you can add a `theme` attribute to the `<monaco-editor>` element.
 
 ```html
-<monaco-editor theme="theme-id"></monaco-editor>
+<monaco-editor theme="OneDark-Pro"></monaco-editor>
 ```
 
 or set it in the `lazy`, `init`, or `hydrate` function.
 
 ```js
 lazy({
-  theme: "theme-id",
+  theme: "OneDark-Pro",
 });
 ```
 
 > [!Note]
 > The theme ID should be one of the [Shiki Themes](https://shiki.style/themes).
 
-### 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.
+`modern-monaco` loads the theme data from the CDN when a theme ID is provided. You can also use a theme from the `tm-themes` package:
 
 ```js
+import OneDark from "tm-themes/themes/OneDark-Pro.json" with { type: "json" };
+
 lazy({
-  langs: ["javascript", "typescript", "css", "html", "json", "markdown"],
+  theme: OneDark
 });
 ```
 
-### Custom Language Grammars
+### Pre-loading Language Grammars
 
-You can also add custom language grammars to the editor.
+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.
 
 ```js
+import markdown from "tm-grammars/markdown.json" with { type: "json" };
+
 lazy({
   langs: [
+    // load language grammars from CDN
+    "html",
+    "css",
+    "javascript",
+    "json",
+
+    // load language grammar from a URL
+    "https://example.com/grammars/mylang.json",
+
+    // load language grammar from a local file
+    "/assets/mylang.json",
+
+    // use `tm-grammars` package without extra http requests, but increases the bundle size
+    markdown,
+
+    // dynamically import
+    () => import("tm-grammars/markdown.json", { with: { type: "json" } }),
+
     // hand-crafted language grammar
     {
       name: "mylang",
       scopeName: "source.mylang",
       patterns: [/* ... */],
     },
-    // or load a grammar from URL
-    "https://example.com/grammars/mylang.json",
   ],
+  // the CDN for loading language grammars and themes, default is "https://esm.sh"
+  tmDownloadCDN: "https://unpkg.com",
 });
 ```
 
@@ -268,7 +302,7 @@ You can set the editor options in the `<monaco-editor>` element as attributes. T
 
 ```html
 <monaco-editor
-  theme="theme-id"
+  theme="OneDark-Pro"
   fontFamily="Geist Mono"
   fontSize="16"
 ></monaco-editor>
@@ -279,45 +313,42 @@ For SSR mode, you can set the editor options in the `renderToWebComponent` funct
 ```js
 import { renderToWebComponent } from "modern-monaco/ssr";
 
-const html = renderToWebComponent({
-  // render options
-  filename: "main.js",
-  code: `console.log("Hello, world!")`,
-  userAgent: req.headers.get("user-agent"), // font detection for different platforms
-  // ...
-
-  // editor options
-  theme: "theme-id",
-  fontFamily: "Geist Mono",
-  fontSize: 16,
-  // ...
-});
+const html = await renderToWebComponent(
+  `console.log("Hello, world!")`,
+  {
+    theme: "OneDark-Pro",
+    language: "javascript",
+    fontFamily: "Geist Mono",
+    fontSize: 16,
+  },
+);
 ```
 
 For manual mode, check [here](https://microsoft.github.io/monaco-editor/docs.html#functions/editor.create.html) for more details.
 
-## Language Server Protocol(LSP)
+## Language Server Protocol (LSP)
 
-`modern-monaco` by default supports full LSP features for following languages:
+`modern-monaco` by default supports full LSP features for the following languages:
 
-- **HTML**
-- **CSS/SCSS/LESS**
-- **JavaScript/TypeScript**
-- **JSON**
+- HTML
+- CSS/SCSS/LESS
+- JavaScript/TypeScript
+- JSON
 
 Plus, `modern-monaco` also supports features like:
 
-- **File System Provider for import completions**
-- **Embedded languages in HTML**
-- **Auto-closing HTML/JSX tags**
+- File System Provider for import completions
+- Embedded languages in HTML
+- 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 required LSP workers.
+> `modern-monaco` will automatically load the required LSP workers.
 
 ### LSP language configuration
 
-You can configure builtin LSPs in the `lazy`, `init`, or `hydrate` function.
+You can configure built-in LSPs in the `lazy`, `init`, or `hydrate` function.
 
 ```js
 lazy({
@@ -341,6 +372,7 @@ export interface LSPLanguageConfig {
   };
   css?: {};
   json?: {
+    /** JSON schemas for JSON language service. */
     schemas?: JSONSchemaSource[];
   };
   typescript?: {
@@ -348,12 +380,22 @@ export interface LSPLanguageConfig {
     compilerOptions?: ts.CompilerOptions;
     /** The global import map. */
     importMap?: ImportMap;
-    /** The version of the typescript from CDN. Default: ">= 5.0.0" */
+    /** The version of TypeScript from the CDN. Default: ">= 5.0.0" */
     tsVersion?: string;
   };
 }
 ```
 
-### Custom LSP
+## Using `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.
+
+```js
+import { lazy } from "modern-monaco/core";
+
+lazy();
+```
+
+## License
 
-[TODO]
+[MIT License](https://opensource.org/licenses/MIT)

package/dist/cache.js

@@ -86,7 +86,7 @@ var Cache = class {
     await promisifyIDBRequest(tx.put(file));
   }
 };
-var cache = new Cache("monaco:cache");
+var cache = new Cache("modern-monaco-cache");
 var cache_default = cache;
 export {
   cache,