weml-monaco 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -4,9 +4,62 @@ All notable changes to the **Monaco** contribution (`weml-monaco`) are documente
 here. The format is based on [Keep a Changelog](https://keepachangelog.com/), and
 this project adheres to [Semantic Versioning](https://semver.org/).
 
-This package mirrors the language logic of the VS Code extension; entries below
-track the port catching up with the VS Code provider changes (see the root
-`CHANGELOG.md` for the extension).
+This package shares the language logic of the VS Code extension (`weml-support`): older
+entries below track the port catching up with its provider changes; since the shared language
+features, both take the same code.
+
+## [0.7.0] — 2026-10-08
+
+### Added
+- The WEML panel, `weml-monaco/panel` (+ `weml-monaco/panel.css`): the Tools and Search
+  Suggestions of the WEML Tools VS Code extension as a framework-free DOM component
+  (`createWemlPanel`), the same look and behaviour, theme from Monaco's `--vscode-*` variables.
+- `createMonacoPanelHost(editor, options)`: the panel's host for a Monaco editor — tools on the
+  editor, EGW search with the host application's access token, layout in `localStorage`.
+- `createEgwWebAuth(options)`: the EGW sign-in for a web page without one of its own — OIDC
+  code flow + PKCE in a popup, tokens in `sessionStorage` (or `localStorage`), refreshed; spread
+  into `createMonacoPanelHost`'s `search`. The panel shows why a sign-in failed under its button
+  (`signIn` may return a promise).
+- The WEML preview, `weml-monaco/preview` (`createWemlPreview`): a live preview of the editor's
+  document rendered with weml-stylesheet — now an optional peer dependency (`^4.0.0`), needed
+  only by this entry.
+- The preview's scroll sync with the editor, both ways (`scrollSync` option, `setScrollSync`),
+  sharing its line mapping with the VS Code preview; a `transform` may return
+  `{ markup, firstLine }`; double-click on a block goes to its line (`doubleClickToEditor`).
+  It looks like the open file next to it: the editor's background, text and scrollbars (10px,
+  the theme's slider) through `monaco-component` on the pane (`monacoTheme: false` to leave it
+  off), not the page's background and the browser's scrollbars.
+- `TOOL_ITEMS` / `TOOL_GROUPS` / `filterToolItems` / `toolItemsFor(mode)`: everything the Tools
+  offer as one list, grouped Containers / Blocks / Inlines, for a host that builds its own picker.
+- Completion in `<body>` offers a new section with any container — *div + w-para*,
+  *div + w-toc* and *div + w-page* join *div + w-heading* and *div + w-para-group*.
+
+### Changed
+- The WEML panel's Tools: the wrap `<select>` and the Insert buttons are one searchable tag picker
+  drawn as VS Code's quick pick (Enter or a click chooses, the button in the field wraps or
+  inserts; the choice is remembered). It offers every tag of the docs' containers, blocks and
+  inlines — new: `w-para-group`, `w-toc`, a new `div` section (with `w-para`, `w-heading`,
+  `w-para-group`, `w-toc`, or a `w-page` page break), `w-text-block`, `hr`, `w-page`, `br`,
+  the `a id` anchor, and `w-sent` to wrap in. Inputs and buttons are 26px, as in VS Code,
+  whatever the host page's line height; the panes' borders show under Monaco themes too.
+- `createWemlPanel`'s `renumber` option is `mode: 'file' | 'paragraph'`: a paragraph has no
+  Renumber and no `div` sections to insert (`toolItemsFor(mode)`).
+- Diagnostics, hover, completion and the outline come from the language logic shared with the
+  VS Code extension instead of a copy of it — the same problems, tooltips and suggestions in
+  both editors; no change in behaviour or API.
+
+### Deprecated
+- `createWemlToolbar`: use the WEML panel (and `registerWemlEditorActions` for the hotkeys alone).
+
+## [0.6.0] — 2026-10-06
+
+### Added
+- `registerWemlWorker` (`weml-monaco/worker`) and the worker module
+  (`weml-monaco/weml.worker`): the same language with completion, hover, outline
+  and diagnostics computed in a Web Worker, so typing in a large document no
+  longer waits for a full parse per keystroke. The worker mirrors models from
+  their edits and answers only the current version of a model. `registerWeml`
+  and the global build are unchanged.
 
 ## [0.5.2] — 2026-09-26
 

package/README.md

@@ -23,7 +23,8 @@ extension. It provides, for models with language id `weml`:
   HTML ↔ canonical format cycle.
 
 This package does **not** modify the original VS Code extension — it is a
-standalone re-implementation living entirely under `monaco-editor/`.
+standalone re-implementation living entirely in this package (`packages/weml-monaco` of the
+monorepo).
 
 ## Install & build
 
@@ -31,9 +32,9 @@ standalone re-implementation living entirely under `monaco-editor/`.
 npm install weml-monaco
 ```
 
-The package has no runtime dependencies (`node-html-parser` and
-`vscode-html-languageservice` are bundled in) and `monaco-editor` is a peer
-dependency you already have.
+The package has no runtime dependencies (`node-html-parser`,
+`vscode-html-languageservice` and the shared normalizer are bundled in) and
+`monaco-editor` is a peer dependency you already have.
 
 | entry point            | file                    | for                                    |
 | ---------------------- | ----------------------- | -------------------------------------- |
@@ -44,8 +45,8 @@ dependency you already have.
 Working on the package itself:
 
 ```bash
-cd monaco-editor
-npm install
+npm ci                 # at the repository root (npm workspaces)
+cd packages/weml-monaco
 npm run build          # tsup → dist/ (ESM + CJS + IIFE + declarations)
 npm run typecheck      # tsc --noEmit
 npm test               # build + Node smoke test
@@ -99,31 +100,146 @@ formatter directly, call `formatWemlText(source)`.
 Structural validation failures are also available through
 `isWemlStructureValidationFailure(error)` and include a code, line and column.
 
-## Toolbar & editor commands
+## Analysis in a Web Worker
 
-Monaco has no webview panels, so the VS Code toolbar is ported as a **DOM top
-panel** you mount yourself, plus per-editor actions/keybindings. Button
-behaviour is identical to the VS Code toolbar.
+`registerWeml` runs completion, hover, outline and diagnostics on the main
+thread, and each of them parses the whole document for every new model version.
+On a large file — a whole book, a megabyte and more — that is tens of
+milliseconds per keystroke on the thread that handles the keystrokes, and typing
+falls behind. `registerWemlWorker` registers the same language with that work in
+a Web Worker:
 
 ```ts
-import { registerWeml, createWemlToolbar } from 'weml-monaco';
+import * as monaco from 'monaco-editor/editor/editor.api.js';
+import { registerWemlWorker } from 'weml-monaco/worker';
+import WemlWorker from 'weml-monaco/weml.worker?worker'; // Vite
+
+const disposable = registerWemlWorker(monaco, { worker: () => new WemlWorker() });
+// Without Vite's `?worker`:
+// registerWemlWorker(monaco, {
+//     worker: () => new Worker(new URL('weml-monaco/weml.worker', import.meta.url), { type: 'module' }),
+// });
+```
+
+It is an addition, not a replacement: `registerWeml` is unchanged, and an
+application chooses one of the two (registering both doubles every provider).
+The worker runs the very providers `registerWeml` registers, so suggestions,
+hovers, outline and markers are the same; only where they are computed changes.
+
+- The worker mirrors each `weml` model's text and keeps it current from the
+  edits Monaco reports — the main thread never sends the whole text again.
+- A request is answered only for the model's current version: one overtaken by
+  further typing is answered empty without parsing, so holding a key down does
+  not build up a queue of parses.
+- Markers computed for a version the model has since left are dropped.
+- The tokenizer, language configuration and formatting stay on the main thread,
+  as with `registerWeml` — they are cheap or run on demand.
+- `weml-monaco/weml.worker` imports nothing of Monaco at runtime; it needs a
+  bundler (or a module worker) to load, and is ESM only.
+
+`registerWemlWorker(monaco, options)` takes the options of `registerWeml` plus
+`worker`, a function that starts the worker (called once; the worker is
+terminated on `dispose()`). The global `<script>` build (`index.global.js`) has
+no worker variant.
+
+## The WEML panel
+
+The side panel of the WEML Tools VS Code extension — **Tools** (wrap the
+selection, insert snippets, renumber `<div>` ids) and **Search Suggestions**
+(EGW search with ParaId / BookCode and `egw://` links to copy or insert) — as a
+framework-free DOM component: the same panel, look and behaviour as in VS Code
+(the extension's webview bundles this very code). It follows Monaco's theme
+through the `--vscode-*` variables Monaco defines on `.monaco-component`.
+
+```ts
+import { createMonacoPanelHost, registerWeml, registerWemlEditorActions } from 'weml-monaco';
+import { createWemlPanel } from 'weml-monaco/panel';
 
 registerWeml(monaco);
 const editor = monaco.editor.create(container, { model });
+registerWemlEditorActions(monaco, editor);       // the hotkeys (below)
+
+const panel = createWemlPanel(
+  createMonacoPanelHost(editor, {
+    search: {
+      apiUrl: 'https://…',                        // the EGW API
+      getAccessToken: () => auth.token,           // your app's sign-in — the only part you supply
+      signIn: () => auth.login(),
+      onDidChangeSession: (listener) => auth.subscribe(listener),
+    },
+  }),
+  { container: document.getElementById('weml-panel') },
+);
+// panel.dispose() removes it.
+```
 
-const toolbar = createWemlToolbar(monaco, editor, {
-  container: document.getElementById('weml-toolbar'), // where to mount the panel
-  onStatus: (msg) => console.log(msg),                // optional status sink
-  // includeSearchRow: true,   // stub search row (as in VS Code); default true
-  // onSearch: (query, lang) => { ... },
-});
+- `createWemlPanel` (`weml-monaco/panel`, light: UI only) takes any
+  `WemlPanelHost` — tools, an optional search backend, optional storage.
+  `createMonacoPanelHost` (main entry) is that host for a Monaco editor: the
+  tools edit the editor, the search sends your token as a bearer (nothing is
+  sent while signed out), and the layout is remembered in `localStorage`
+  (`storage: false` to opt out). Without `search` the pane says the search is
+  not configured; `search: false` leaves the pane out.
+- An app without a sign-in of its own takes `createEgwWebAuth` — the EGW
+  sign-in (OIDC code flow + PKCE) in a popup, tokens in `sessionStorage`,
+  refreshed before they expire:
+
+  ```ts
+  import { createEgwWebAuth } from 'weml-monaco';
+
+  const auth = createEgwWebAuth({ authority, clientId, scopes: 'openid offline_access search' });
+  createMonacoPanelHost(editor, { search: { apiUrl, ...auth } });
+  auth.signOut();                                 // from the app's own account menu
+  ```
+
+  The popup comes back to `<origin>/auth-callback` (`redirectUri` to change it),
+  which the client must allow; a blank page there is enough. `storage: 'local'`
+  shares the session between tabs. A failed sign-in (popup blocked or closed,
+  refused) shows its message under the Sign in button.
+- The stylesheet is injected into the page by default; it is also published as
+  `weml-monaco/panel.css` (`injectStyles: false` to link it yourself).
+- `mode: 'paragraph'` for an editor of one paragraph (the content of one `<div>`): no Renumber
+  div ids, and no `div + …` sections among the tags to insert. Default: `'file'`.
+
+## The WEML preview
+
+A live preview of the editor's document, rendered with
+[`weml-stylesheet`](../weml-stylesheet) — an **optional peer dependency**:
+install it (and load its CSS) to use this entry; nothing else needs it.
+
+```ts
+import { createWemlPreview } from 'weml-monaco/preview';
+import 'weml-stylesheet/css/weml.scoped.css';
 
-// toolbar.element   → the toolbar DOM node
-// toolbar.dispose()  → removes the panel and its actions
+const preview = createWemlPreview(editor, {
+  container: document.getElementById('weml-preview'),
+  theme: 'dark',              // data-weml-theme; omit to follow prefers-color-scheme
+});
+preview.setTheme('light');
+preview.dispose();
 ```
 
-`createWemlToolbar` also registers the editor actions (so they work without the
-panel too, via keybindings and the command palette):
+It renders at once, then after a pause in typing (`delay`, 300 ms), and at once
+again when the editor gets another model; an unchanged text is not rendered
+twice (a whole book is not cheap). A whole document keeps its `dir` / `lang`
+(right-to-left books render right to left). Blank text shows `emptyText`;
+`transform(text)` picks what to render (e.g. without a wrapper your editor adds).
+
+**Scroll sync**, both ways, as in the VS Code preview (and with the same code,
+weml-language-core's): the rendered blocks carry their source line, so the
+preview follows the editor's top line and the editor follows the preview. Turn
+it off, or one way only, with `scrollSync` — `true` (default), `false`, or
+`{ previewWithEditor, editorWithPreview }` — and later with
+`preview.setScrollSync(...)`; there is no button of its own, the host decides.
+A `transform` that drops lines from the top returns `{ markup, firstLine }` (the
+model line its markup starts on) so the lines still match. A double-click on a
+block puts the editor's cursor on its line (`doubleClickToEditor: false` to
+turn it off).
+
+## Editor commands
+
+`registerWemlEditorActions(monaco, editor, options)` registers the editor
+actions (keybindings and the command palette):
 
 | action / command          | keybinding    | effect                                             |
 | ------------------------- | ------------- | -------------------------------------------------- |
@@ -133,38 +249,36 @@ panel too, via keybindings and the command palette):
 | `weml.cycleFormat`        | `Alt+Shift+F` | cycle document: HTML ↔ canonical WEML formatting   |
 | `weml.renumberDivIds`     | —             | renumber every `<div>` id to a sequential 1…n      |
 
-To register the actions without a toolbar, call
-`registerWemlEditorActions(monaco, editor, options)`. The underlying operations
-(`wrapSelection`, `insertSnippetById`, `renumberDivIds`, `cycleFormat`) and the
-pure helpers (`planDivIdRenumber`, `buildWrapSnippet`) are exported too.
+The underlying operations (`wrapSelection`, `insertSnippetById`,
+`renumberDivIds`, `cycleFormat`) and the pure helpers (`planDivIdRenumber`,
+`buildWrapSnippet`) are exported too. Snippet insertion uses Monaco's
+`snippetController2`, so `$1`/`$2` tab stops behave like `editor.insertSnippet`
+in VS Code.
 
-Snippet insertion uses Monaco's `snippetController2`, so `$1`/`$2` tab stops
-behave like `editor.insertSnippet` in VS Code.
+### `createWemlToolbar` (deprecated)
 
-## Demo
+The earlier flat DOM toolbar (`createWemlToolbar(monaco, editor, { container,
+onStatus })`) still works and still registers the editor actions, but it is
+deprecated in favour of the WEML panel and gets no new features.
 
-```bash
-npm run demo        # builds dist/ and copies the IIFE bundle → demo/weml-monaco.js
-# then open demo/index.html in a browser
-```
+## Trying it out
 
-`demo/index.html` loads Monaco from a CDN (AMD loader) and the WEML bundle as a
-global, registers the language and opens a sample document. Try Ctrl+Space for
-completions, hover a tag, "Format Document", Ctrl+Shift+O for the outline, or
-introduce an error to see diagnostics.
+The monorepo's dev app, [`weml-storybook`](../weml-storybook)
+(`npm start -w weml-storybook` from the repository root), runs this package from
+its sources in a full editor: completions (Ctrl+Space), hover, "Format
+Document", the outline, diagnostics and the toolbar.
 
 ## How it relates to the VS Code extension
 
-The schema and rules are reused verbatim from the extension:
+The language logic is shared with the VS Code extensions, not copied — two workspace packages,
+bundled into every build (neither is a runtime dependency):
 
-| reused as-is                         | adapted for Monaco                       |
+| shared (workspace package)           | adapted for Monaco                       |
 | ------------------------------------ | ---------------------------------------- |
-| `generated/schema.ts`                | `schema/docs.ts` (plain `IMarkdownString`) |
-| `schema/structureRules.ts`           | `wemlDocument.ts` (model ↔ LSP positions) |
-| `schema/snippets.ts`                 | `providers/*` (Monaco provider APIs)     |
-| `wemlContentNormalizeV2.js`          | `index.ts` (registration + diagnostics)  |
-
-Parsing still uses `vscode-html-languageservice` (it is editor-agnostic and
-runs in the browser); the only real work was swapping the `vscode.*` provider
-APIs for `monaco.languages.*` and converting between Monaco's 1-based
-line/column positions and the language service's 0-based LSP positions.
+| `weml-language-core`: schema, structure rules, snippets, entities, markdown text, the language features (diagnostics, hover, completion, outline), tool model, wrap / renumber | `schema/docs.ts` (plain `IMarkdownString`) |
+| `weml-normalizer`: the canonical normalizer | `wemlDocument.ts` (parse cache, offsets ↔ Monaco positions), `providers/*` (the features' data → Monaco provider types), `index.ts` (registration + diagnostics) |
+
+The diagnostics, tooltips, suggestions and outline are computed once, in the shared package, as
+plain data with offsets — the VS Code extension and this package only map them to their editor's
+types, so both editors report the same problems and offer the same items. Parsing uses
+`vscode-html-languageservice` (editor-agnostic, runs in the browser and in the worker).