@aiursoft/uistack-markdown-ui 1.2.23 → 1.2.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +206 -3
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,31 +1,234 @@
1
- # MarkdownUI.js
1
+ <a name="markdownuijs"></a>
2
+
3
+ # Aiursoft MarkdownUI.js
2
4
 
3
5
  [![Pipeline](https://badge-proxy.aiursoft.com/aiursoft/MarkdownUI.js/badges/master/pipeline.svg)](https://gitlab.aiursoft.com/aiursoft/MarkdownUI.js/-/pipelines) [![npm](https://img.shields.io/npm/v/@aiursoft/uistack-markdown-ui)](https://www.npmjs.com/package/@aiursoft/uistack-markdown-ui)
4
6
 
5
7
  Shared Markdown rendering, editing and reading components.
6
8
 
7
- ## Install
9
+ ## Overview
10
+
11
+ ### What is MarkdownUI.js?
12
+
13
+ Shared Markdown rendering, editing and reading components.
14
+
15
+ <a name="install"></a>
16
+
17
+ ## Installation
18
+
19
+ Install the package in your project:
8
20
 
9
21
  ```bash
10
22
  npm install @aiursoft/uistack-markdown-ui
11
23
  ```
12
24
 
25
+ The package provides ESM, CommonJS, TypeScript declarations and a browser IIFE build (`AiursoftMarkdownUi`). Browser editing and reading require the DOM; `renderMarkdown` can also be used from a Node.js module. Monaco, Mermaid and MathJax are supplied by the application when those integrations are needed.
26
+
13
27
  ## Usage
14
28
 
29
+ Save the following as `index.html` beside `node_modules/` and serve that directory over HTTP with your existing static-file server:
30
+
31
+ ```html
32
+ <!doctype html>
33
+ <html lang="en">
34
+ <meta charset="utf-8">
35
+ <title>MarkdownUI example</title>
36
+ <body>
37
+ <div id="preview"></div>
38
+ <script src="./node_modules/@aiursoft/uistack-markdown-ui/dist/index.global.js"></script>
39
+ <script>
40
+ const preview = document.getElementById('preview');
41
+ preview.innerHTML = AiursoftMarkdownUi.renderMarkdown('# Hello');
42
+ </script>
43
+ </body>
44
+ </html>
45
+ ```
46
+
47
+ **Bundler import**
48
+
49
+ In an application bundle, create or select the preview element before assigning the rendered HTML:
50
+
15
51
  ```js
16
52
  import { renderMarkdown } from '@aiursoft/uistack-markdown-ui';
17
53
 
54
+ const preview = document.getElementById('preview');
18
55
  preview.innerHTML = renderMarkdown('# Hello');
19
56
  ```
20
57
 
21
58
  See [usage and API](docs/usage.md) for editors, readers, image uploads and print integration.
22
59
 
60
+ ### Complete Markdown editor
61
+
62
+ `createMarkdownEditor` owns the common editor behavior while the application remains
63
+ responsible for loading Monaco. Passing a loader instead of importing Monaco keeps it
64
+ out of application bundles and works with the standard Monaco AMD loader.
65
+
66
+ ```js
67
+ import { createMarkdownEditor, loadMonacoFromAmd } from "@aiursoft/uistack-markdown-ui";
68
+
69
+ const markdownEditor = await createMarkdownEditor({
70
+ editorContainer: document.querySelector("#markdown-editor"),
71
+ textarea: document.querySelector("#markdown-source"),
72
+ previewContainer: document.querySelector("#markdown-preview"),
73
+ editorPane: document.querySelector("#editor-pane"),
74
+ previewPane: document.querySelector("#preview-pane"),
75
+ form: document.querySelector("form"),
76
+ loadMonaco: () => loadMonacoFromAmd(),
77
+ theme: "vs-dark",
78
+ uploadUrl: "/api/files/upload",
79
+ initialViewMode: "split",
80
+ viewModeStorageKey: "markdown-view-mode",
81
+ viewModeControls: [
82
+ { element: document.querySelector("#edit-mode"), mode: "editor" },
83
+ { element: document.querySelector("#split-mode"), mode: "split" },
84
+ { element: document.querySelector("#preview-mode"), mode: "preview" }
85
+ ],
86
+ hljs,
87
+ mermaid,
88
+ MathJax,
89
+ onSave: markdown => saveMarkdown(markdown),
90
+ onInitializationError: error => console.error("Monaco failed to initialize", error),
91
+ onPreviewError: error => console.error("Markdown preview failed", error)
92
+ });
93
+
94
+ await markdownEditor.setViewMode("preview");
95
+ markdownEditor.syncTextarea();
96
+ markdownEditor.setValue("# Updated");
97
+ markdownEditor.focus();
98
+ markdownEditor.dispose();
99
+ ```
100
+
101
+ The controller initializes Monaco for Markdown, keeps the original textarea synchronized,
102
+ debounces secure preview rendering, enhances highlight.js/Mermaid/MathJax, supports image
103
+ paste and drop, and applies consistent professional Monaco defaults (14px Cascadia Code
104
+ font stack, ligatures, semantic highlighting and comfortable vertical padding). Applications
105
+ can still override individual Monaco settings through `editorOptions`.
106
+
107
+ It also registers consistent Markdown shortcuts:
108
+
109
+ - <kbd>Ctrl/Cmd+B</kbd>: bold
110
+ - <kbd>Ctrl/Cmd+I</kbd>: italic
111
+ - <kbd>Ctrl/Cmd+K</kbd>: inline or fenced code
112
+ - <kbd>Ctrl/Cmd+L</kbd>: link
113
+ - <kbd>Ctrl/Cmd+1</kbd> through <kbd>Ctrl/Cmd+6</kbd>: headings
114
+ - <kbd>Ctrl/Cmd+S</kbd>: `onSave`
115
+ - <kbd>Enter</kbd>: continue bullet and ordered lists
116
+
117
+ If Monaco cannot be loaded, the original textarea becomes visible and continues to drive
118
+ the same preview. Applications therefore use one fallback policy instead of implementing
119
+ their own. Preview enhancement errors are reported through `onPreviewError` and never
120
+ replace a working Monaco editor. `onError` remains as a deprecated compatibility callback
121
+ for both error categories.
122
+
123
+ ### Reading pages
124
+
125
+ ```js
126
+ import {
127
+ initializeMarkdownReader,
128
+ printMarkdown
129
+ } from "@aiursoft/uistack-markdown-ui";
130
+
131
+ await initializeMarkdownReader({
132
+ container: ".markdown-body",
133
+ hljs,
134
+ mermaid,
135
+ MathJax
136
+ });
137
+
138
+ printButton.addEventListener("click", () =>
139
+ printMarkdown({ container: ".markdown-body", hljs, mermaid, MathJax }));
140
+ ```
141
+
142
+ Only code blocks inside the supplied container are highlighted. Mermaid is always
143
+ initialized in strict security mode. The reader also applies the shared responsive
144
+ Bootstrap table treatment and opens rendered links with `noopener noreferrer`.
145
+
146
+ ### Image paste and drop
147
+
148
+ ```js
149
+ import { attachImageUpload } from "@aiursoft/uistack-markdown-ui";
150
+
151
+ const uploads = attachImageUpload({
152
+ editor,
153
+ eventTarget: editorContainer.parentElement,
154
+ uploadUrl: "/api/files/upload",
155
+ onError: (error, file) => console.error(`Failed to upload ${file.name}`, error)
156
+ });
157
+
158
+ // Call uploads.dispose() when the editor is destroyed.
159
+ ```
160
+
161
+ The default queue uploads three files concurrently and retries HTTP 429 responses up
162
+ to five times. Clipboard images are accepted from both `clipboardData.files` and
163
+ `clipboardData.items`, and are captured before Monaco consumes the paste event. Use
164
+ the parent of Monaco's host container as `eventTarget`; `createMarkdownEditor()` does
165
+ this automatically. Use `getImageUrl` when an endpoint does not return
166
+ `internetPath` or `InternetPath`.
167
+
168
+ ### Aiursoft application contract
169
+
170
+ MarkToHtml, MoongladeV2, EmployeeCenter and Kanban use the global IIFE build and the
171
+ same `createMarkdownEditor` contract. Monaco, live preview, highlight.js, Mermaid,
172
+ MathJax, Markdown shortcuts, image paste/drop, editor/split/preview modes and the
173
+ textarea fallback are required capabilities for these full editors.
174
+
175
+ DocsViewer and HowToCookViewer are reader-only consumers. Their Markdown containers
176
+ use `initializeMarkdownReader` for highlighting, Mermaid, MathJax, responsive tables
177
+ and safe external-link behavior.
178
+
179
+ Translate is an intentional product-level exception. It keeps its lightweight
180
+ CodeMirror Markdown input because translation does not need code highlighting,
181
+ Mermaid, MathJax, uploads or the full editing toolbar. It must not be treated as an
182
+ incomplete migration.
183
+
184
+ ## Configuration
185
+
186
+ Configuration is passed as JavaScript options; the package has no configuration file or environment variables. The complete editor example above shows the application-owned DOM elements, Monaco loader, view controls, upload endpoint and callbacks.
187
+
188
+ **Rendering**
189
+
190
+ `renderMarkdown(markdown, options)` and `createMarkdownIt(options)` accept `breaks` (default `false`), `linkify` (`true`) and `typographer` (`true`). Native HTML is always disabled. Mermaid processing uses strict security mode. Math and diagram rendering require the corresponding application-supplied integrations; syntax highlighting is included in the renderer.
191
+
192
+ **Editor options and lifecycle**
193
+
194
+ `editorContainer`, `textarea` and `previewContainer` are required. Supply `monaco` or `loadMonaco` to create the editor; initialization failure reveals the textarea fallback. `theme` defaults to `vs`, `debounceMs` to `200`, and `initialViewMode` to `split`. `editorOptions` overrides Monaco editor settings. `form` defaults to the textarea's form; `editorPane` and `previewPane` default to their containers. `viewModeControls` defaults to an empty list; when `viewModeStorageKey` is supplied, a valid saved view mode overrides the initial mode. `markdownOptions`, `mermaidTheme`, `hljs`, `mermaid` and `MathJax` configure preview integration.
195
+
196
+ `onSave`, `onChange` and `onPreviewRendered` report edits and rendering. Use `onInitializationError` and `onPreviewError` for their separate failure categories; deprecated `onError` remains a compatibility callback. An optional `uploadUrl` enables image uploading, with `imageUploadOptions` for its settings. Call the returned controller's `dispose()` when the editor is removed.
197
+
198
+ **Reader options**
199
+
200
+ `initializeMarkdownReader` and `printMarkdown` take a required `container` selector, element or iterable, plus optional highlighter, Mermaid and MathJax dependencies (otherwise resolved from globals). `decorateTables` and `openLinksInNewTab` default to enabled. Tables use `table`, `table-striped` and `table-bordered` classes with a `table-responsive` wrapper; override `tableClassNames` or `tableWrapperClassName` when needed. Links opened in a new tab receive `noopener noreferrer`. `mermaidTheme` selects the diagram theme.
201
+
202
+ **Image upload options**
203
+
204
+ `editor` and `uploadUrl` are required for `attachImageUpload`. `eventTarget` defaults to the editor DOM node when available; without either target no DOM paste/drop listeners are attached. A Monaco host parent captures paste events before the editor. `fieldName` defaults to `file`, `concurrency` to `3` and `maxRetries` to `5`. Only HTTP 429 is retried, using `Retry-After` when present. Supply `fetch` to replace the fetch implementation, `getImageUrl` to customize response parsing (defaults to `internetPath` or `InternetPath`), and `onError` to report failures. Dispose the upload controller with the editor. The host provides and secures the upload endpoint.
205
+
23
206
  ## Development
24
207
 
25
- Build with Node.js 22.18+ (22.x), 24.11+ (24.x), or 26+.
208
+ Build with Node.js 22.18+ (22.x), 24.11+ (24.x), or 26+. The current build is verified with Node.js 24.
209
+
210
+ From the repository root, install the locked dependencies, run the existing checks and create a package:
26
211
 
27
212
  ```bash
28
213
  npm ci
29
214
  npm run check
30
215
  npm pack
31
216
  ```
217
+
218
+ The existing checks run TypeScript checking, Vitest coverage tests and the production build. `npm pack` creates a local archive; it does not publish a release.
219
+
220
+ ## Documentation
221
+
222
+ See [usage and API](docs/usage.md) for editors, readers, image uploads and print integration. Exported option types and lifecycle contracts are in [src/index.ts](src/index.ts).
223
+
224
+ ## How to contribute
225
+
226
+ There are many ways to contribute to the project: logging bugs, submitting pull requests, reporting issues, and creating suggestions.
227
+
228
+ Even if you have push rights on the repository, you should create a personal fork and create feature branches there when you need them. This keeps the main repository clean and your workflow cruft out of sight.
229
+
230
+ We're also interested in your feedback on the future of this project. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.
231
+
232
+ ## License
233
+
234
+ Licensed under the [MIT License](LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aiursoft/uistack-markdown-ui",
3
- "version": "1.2.23",
3
+ "version": "1.2.25",
4
4
  "description": "Shared, secure Markdown editing and reading utilities for Aiursoft applications.",
5
5
  "license": "MIT",
6
6
  "type": "module",