weml-monaco 0.10.1 → 0.11.1

package/CHANGELOG.md

@@ -8,6 +8,31 @@ This package shares the language logic of the VS Code extension (`weml-support`)
 entries below track the port catching up with its provider changes; since the shared language
 features, both take the same code.
 
+## [0.11.1] — 2026-10-15
+
+### Changed
+- The README is trimmed to what a user of the package needs.
+
+## [0.11.0] — 2026-10-14
+
+### Added
+- `fixedWrappers` (paragraph mode, `createWemlEditor` and `<WemlEditor>`): fixed tags between the
+  `<div id="1">` and the content, outermost first — a name or `{ tag, attributes }`. `['w-para']`
+  edits the content of a `<w-para>`, as a publication's description is: `<div id="1"><w-para>` …
+  `</w-para></div>`, both lines locked as the `<div>` was, `getValue()` / `onChange` the content
+  inside them, the preview rendering it inside them (without the `<div>`). A chain WEML's structure
+  rules reject throws when the editor is created; with any, an empty value starts empty (the
+  templates are a document and a `<w-para>`).
+
+### Changed
+- The options and the props are split by `mode` (`WemlEditorFileModeOptions` /
+  `WemlEditorParagraphModeOptions`, `WemlEditorFileModeProps` / `WemlEditorParagraphModeProps`):
+  `hideWrapper` and `fixedWrappers` type-check only with `mode: 'paragraph'`, `onFileLoad` and
+  `onFileSave` only in a file. A host that wraps the props in `Omit` needs a distributive one, or
+  the split is lost. No change at runtime.
+
+VS Code has no counterpart: it edits files only; the paragraph mode is the web editor's.
+
 ## [0.10.1] — 2026-10-14
 
 ### Changed

package/README.md

@@ -26,7 +26,7 @@ This package does **not** modify the original VS Code extension — it is a
 standalone re-implementation living entirely in this package (`packages/weml-monaco` of the
 monorepo).
 
-## Install & build
+## Install
 
 ```bash
 npm install weml-monaco
@@ -44,17 +44,6 @@ The package has no runtime dependencies (`node-html-parser`,
 | `weml-monaco/editor`   | `dist/editor.mjs`       | the editor and its workbench (below)   |
 | `weml-monaco/react`    | `dist/react.mjs`        | the editor as a React component        |
 
-Working on the package itself:
-
-```bash
-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
-npm run check:package  # publint + arethetypeswrong on the packed tarball
-```
-
 ## Usage
 
 Monaco is **passed in** at registration time, so this works no matter how
@@ -187,7 +176,15 @@ weml.dispose();
 - `mode: 'paragraph'` edits one paragraph (the content of one `<div>`): the model
   holds it inside a `<div id="1">` wrapper the language needs, guarded against
   edits (dimmed, or hidden with `hideWrapper`); `getValue()` is the paragraph alone,
-  and there is no Contents.
+  and there is no Contents. `fixedWrappers` puts fixed tags between the `<div>` and
+  the content, outermost first — `['w-para']` edits the content of a `<w-para>` (a
+  publication's description): the model is `<div id="1"><w-para>` … `</w-para></div>`,
+  both lines locked, `getValue()` the content inside them, the preview renders it
+  inside them. A tag is a name or `{ tag, attributes }`; one WEML does not allow
+  inside the one before it throws, and with any an empty value starts empty.
+- The options and the component's props are split by `mode`: a paragraph's
+  (`hideWrapper`, `fixedWrappers`) do not type-check in a file, a file's (`onFileLoad`,
+  `onFileSave`) not in a paragraph.
 - **Files on disk** (`file` mode): Open File (Ctrl+O, or a `.weml` dropped on the
   editor) and Save to Disk (Ctrl+Shift+S: the name asked for at the top, suggested
   `<name>-<timestamp>.weml`; Chromium's save dialog where there is one) in the
@@ -329,7 +326,7 @@ const panel = createWemlPanel(
 ## The WEML preview
 
 A live preview of the editor's document, rendered with
-[`weml-stylesheet`](../weml-stylesheet) — an **optional peer dependency**:
+[`weml-stylesheet`](https://github.com/Burjuy/weml-language-vscode-extension/tree/main/packages/weml-stylesheet) — an **optional peer dependency**:
 install it (and load its CSS) to use this entry; nothing else needs it.
 
 ```ts
@@ -426,25 +423,3 @@ in VS Code.
 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.
-
-## Trying it out
-
-The monorepo's dev app, [`storybook/`](../../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 language logic is shared with the VS Code extensions, not copied — two workspace packages,
-bundled into every build (neither is a runtime dependency):
-
-| shared (workspace package)           | adapted for Monaco                       |
-| ------------------------------------ | ---------------------------------------- |
-| `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).

package/dist/editor.cjs

@@ -37666,16 +37666,36 @@ async function saveWemlFile(text, suggestedName) {
 }
 
 // src/editor/content.ts
-var WRAPPER_OPENER = '<div id="1">';
-var WRAPPER_CLOSER = "</div>";
-function initialModelText(mode, content) {
-  return mode === "file" ? content : `${WRAPPER_OPENER}
+var DIV_OPENER = '<div id="1">';
+var DIV_CLOSER = "</div>";
+var DEFAULT_WRAPPER = { opener: DIV_OPENER, closer: DIV_CLOSER, innerOpener: "", innerCloser: "" };
+var escapeAttribute2 = (value) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+function contentWrapper(fixedWrappers = []) {
+  if (fixedWrappers.length === 0) return DEFAULT_WRAPPER;
+  const tags = fixedWrappers.map((wrapper) => typeof wrapper === "string" ? { tag: wrapper } : wrapper);
+  let parent = "div";
+  for (const { tag } of tags) {
+    const rule = STRUCTURE_RULES[parent];
+    if (!rule?.children.some((group) => group.tags.includes(tag))) {
+      throw new Error(`weml-monaco: fixedWrappers \u2014 <${tag}> is not allowed inside <${parent}>.`);
+    }
+    parent = tag;
+  }
+  const innerOpener = tags.map(({ tag, attributes }) => {
+    const attrs = Object.entries(attributes ?? {}).map(([name, value]) => ` ${name}="${escapeAttribute2(value)}"`);
+    return `<${tag}${attrs.join("")}>`;
+  }).join("");
+  const innerCloser = tags.map(({ tag }) => `</${tag}>`).reverse().join("");
+  return { opener: DIV_OPENER + innerOpener, closer: innerCloser + DIV_CLOSER, innerOpener, innerCloser };
+}
+function initialModelText(mode, content, wrapper = DEFAULT_WRAPPER) {
+  return mode === "file" ? content : `${wrapper.opener}
 ${content}
-${WRAPPER_CLOSER}`;
+${wrapper.closer}`;
 }
-function isWrapperIntact(model) {
+function isWrapperIntact(model, wrapper = DEFAULT_WRAPPER) {
   const lineCount = model.getLineCount();
-  return lineCount >= 3 && model.getLineContent(1) === WRAPPER_OPENER && model.getLineContent(lineCount) === WRAPPER_CLOSER;
+  return lineCount >= 3 && model.getLineContent(1) === wrapper.opener && model.getLineContent(lineCount) === wrapper.closer;
 }
 function paragraphRange(model) {
   const lastLine = model.getLineCount() - 1;
@@ -37686,9 +37706,9 @@ function contentRange(model, mode) {
   const lastLine = model.getLineCount();
   return { startLineNumber: 1, startColumn: 1, endLineNumber: lastLine, endColumn: model.getLineMaxColumn(lastLine) };
 }
-function readContent(model, mode) {
+function readContent(model, mode, wrapper = DEFAULT_WRAPPER) {
   if (mode === "file") return model.getValue();
-  return isWrapperIntact(model) ? model.getValueInRange(paragraphRange(model)) : null;
+  return isWrapperIntact(model, wrapper) ? model.getValueInRange(paragraphRange(model)) : null;
 }
 function contentLineOffset(mode, hideWrapper) {
   return mode === "paragraph" && hideWrapper ? 1 : 0;
@@ -37726,17 +37746,17 @@ function findMatches(value, query, options) {
   if (query === "") return [];
   return [...value.matchAll(toRegExp(query, options))].filter((match) => match[0] !== "");
 }
-function createContentApi(editor, mode, lineOffset, initialValue) {
+function createContentApi(editor, mode, lineOffset, initialValue, wrapper = DEFAULT_WRAPPER) {
   let lastWhole = initialValue;
   const read = () => {
     const model = editor.getModel();
-    const content = model ? readContent(model, mode) : null;
+    const content = model ? readContent(model, mode, wrapper) : null;
     if (content !== null) lastWhole = content;
     return lastWhole;
   };
   const bounds = () => {
     const model = editor.getModel();
-    const content = model && readContent(model, mode);
+    const content = model && readContent(model, mode, wrapper);
     if (!model || content === null) return void 0;
     const { startLineNumber, startColumn } = contentRange(model, mode);
     return { model, start: model.getOffsetAt({ lineNumber: startLineNumber, column: startColumn }), length: content.length };
@@ -38236,13 +38256,16 @@ function injectEditorStyles(doc = document) {
 // src/editor/wrapperGuard.ts
 var HIDDEN_AREAS_SOURCE = "weml-editor.wrapper";
 var WRAPPER_LINE_CLASS = "weml-editor-wrapper-line";
-var WRAPPER_MESSAGE = { value: "The `<div id>` wrapper is not part of the paragraph and cannot be edited." };
-function guardWrapper(m2, editor, hideWrapper, hostOptions) {
+var wrapperMessage = (wrapper) => ({
+  value: `The \`${wrapper.opener}\` wrapper is not part of the content and cannot be edited.`
+});
+function guardWrapper(m2, editor, hideWrapper, hostOptions, wrapper = DEFAULT_WRAPPER) {
   const model = editor.getModel();
   if (!model) return { dispose() {
   }, setHostOptions() {
   } };
   let host = hostOptions;
+  const message = wrapperMessage(wrapper);
   const disposables = [];
   const touchesWrapper = (selection) => selection.startLineNumber < 2 || selection.endLineNumber > model.getLineCount() - 1;
   const clampSelections = () => {
@@ -38263,7 +38286,7 @@ function guardWrapper(m2, editor, hideWrapper, hostOptions) {
   const syncReadOnly = () => {
     const locked = (editor.getSelections() ?? []).some(touchesWrapper);
     const readOnly = host.readOnly === true || locked;
-    const readOnlyMessage = locked && host.readOnly !== true ? WRAPPER_MESSAGE : host.readOnlyMessage;
+    const readOnlyMessage = locked && host.readOnly !== true ? message : host.readOnlyMessage;
     if (applied?.readOnly === readOnly && applied.readOnlyMessage === readOnlyMessage) return;
     applied = { readOnly, readOnlyMessage };
     editor.updateOptions({ readOnly, readOnlyMessage });
@@ -38321,7 +38344,7 @@ function guardWrapper(m2, editor, hideWrapper, hostOptions) {
   let repairPending = false;
   disposables.push(
     editor.onDidChangeModelContent(() => {
-      if (isWrapperIntact(model)) {
+      if (isWrapperIntact(model, wrapper)) {
         showWrapper();
         return;
       }
@@ -38329,7 +38352,7 @@ function guardWrapper(m2, editor, hideWrapper, hostOptions) {
       repairPending = true;
       queueMicrotask(() => {
         repairPending = false;
-        if (!model.isDisposed() && !isWrapperIntact(model)) model.undo();
+        if (!model.isDisposed() && !isWrapperIntact(model, wrapper)) model.undo();
       });
     })
   );
@@ -38440,8 +38463,9 @@ var actionButton = (icon2, title, run) => {
   return node;
 };
 function createWemlEditor(m2, container, options = {}) {
-  if (options.injectStyles !== false) injectEditorStyles();
   const mode = options.mode ?? "file";
+  const wrapper = options.mode === "paragraph" ? contentWrapper(options.fixedWrappers) : DEFAULT_WRAPPER;
+  if (options.injectStyles !== false) injectEditorStyles();
   const parts = {
     tools: options.parts?.tools ?? true,
     activityBar: options.parts?.activityBar ?? true,
@@ -38479,20 +38503,20 @@ function createWemlEditor(m2, container, options = {}) {
   const language = acquireLanguage(m2, options);
   const { analysis, formatter } = language.registration;
   const given = options.value ?? "";
-  const initialValue = given.trim() || options.withDefaultContent === false ? given : mode === "file" ? NEW_WEML_DOCUMENT : NEW_WEML_PARAGRAPH;
+  const initialValue = given.trim() || options.withDefaultContent === false || wrapper !== DEFAULT_WRAPPER ? given : mode === "file" ? NEW_WEML_DOCUMENT : NEW_WEML_PARAGRAPH;
   const editorId = ++editorCount;
-  const model = m2.editor.createModel(initialModelText(mode, initialValue), "weml", m2.Uri.parse(`inmemory://weml-editor/${editorId}/${encodeURIComponent(fileName)}`));
+  const model = m2.editor.createModel(initialModelText(mode, initialValue, wrapper), "weml", m2.Uri.parse(`inmemory://weml-editor/${editorId}/${encodeURIComponent(fileName)}`));
   const root = element("div", { className: `${EDITOR_CLASS} monaco-component` });
   const editorHost = element("div", { className: "wb-editor wb-part" });
   const baseOptions = { ...EDITOR_OPTIONS, ...options.editorOptions };
   const editor = m2.editor.create(editorHost, { ...baseOptions, ...layout.editorOptions, model });
-  const wrapperGuard = mode === "paragraph" ? guardWrapper(m2, editor, options.hideWrapper ?? false, { ...baseOptions, ...layout.editorOptions }) : void 0;
+  const wrapperGuard = mode === "paragraph" ? guardWrapper(m2, editor, options.hideWrapper ?? false, { ...baseOptions, ...layout.editorOptions }, wrapper) : void 0;
   if (wrapperGuard) disposables.push(wrapperGuard);
   const applyEditorOptions = (next) => {
     editor.updateOptions(next);
     wrapperGuard?.setHostOptions(next);
   };
-  const content = createContentApi(editor, mode, lineOffset, initialValue);
+  const content = createContentApi(editor, mode, lineOffset, initialValue, wrapper);
   const valueListeners = /* @__PURE__ */ new Set();
   const problemListeners = /* @__PURE__ */ new Set();
   const cursorListeners = /* @__PURE__ */ new Set();
@@ -38501,7 +38525,7 @@ function createWemlEditor(m2, container, options = {}) {
   let problems = [];
   disposables.push(
     model.onDidChangeContent(() => {
-      const value = readContent(model, mode);
+      const value = readContent(model, mode, wrapper);
       if (value === null || value === lastValue) return;
       lastValue = value;
       for (const listener of valueListeners) listener(value);
@@ -38800,11 +38824,12 @@ function createWemlEditor(m2, container, options = {}) {
       language: previewLanguage,
       scrollSync: previewScrollSync,
       container: host,
-      // A paragraph without its wrapper, from the model's second line (the scroll sync matches
-      // the blocks to the model's lines); a broken wrapper: the whole text, as typed.
+      // A paragraph without its `<div>`, from the model's second line (the scroll sync matches
+      // the blocks to the model's lines), inside its `fixedWrappers` so it is styled as their
+      // content; a broken wrapper: the whole text, as typed.
       transform: mode === "paragraph" ? (text) => {
-        const paragraph = readContent(model, mode);
-        return paragraph === null ? text : { markup: paragraph, firstLine: 1 };
+        const paragraph = readContent(model, mode, wrapper);
+        return paragraph === null ? text : { markup: wrapper.innerOpener + paragraph + wrapper.innerCloser, firstLine: 1 };
       } : void 0
     });
     return { element: host, dispose: () => preview.dispose(), preview };
@@ -39421,7 +39446,7 @@ function createWemlEditor(m2, container, options = {}) {
     reset(value) {
       baseline = value;
       lastValue = value;
-      model.setValue(initialModelText(mode, value));
+      model.setValue(initialModelText(mode, value, wrapper));
       renderTab();
       renderSave();
     },