@aiursoft/uistack-markdown-ui 1.2.6 → 1.2.7

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 (4) hide show
  1. package/LICENSE +61 -0
  2. package/README.md +12 -134
  3. package/docs/usage.md +151 -0
  4. package/package.json +4 -4
package/LICENSE ADDED
@@ -0,0 +1,61 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Aiursoft
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ # Developer Certificate of Origin
24
+
25
+ In addition to the permissions and conditions stated above, the maintenance and development of the Software shall adhere to the following Aiursoft Principles:
26
+
27
+ 1. Any compiled artifacts of the Software must be capable of performing their full functions without requiring an internet connection.
28
+ 2. The source code of the Software must be capable of being compiled locally within Aiursoft's infrastructure without requiring an internet connection.
29
+ 3. The source code of the Software must be capable of being compiled locally by third-party developers with an internet connection.
30
+
31
+ # Our Pledge
32
+
33
+ In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
34
+
35
+ # Our Standards
36
+
37
+ Examples of behavior that contributes to creating a positive environment include:
38
+
39
+ - Using welcoming and inclusive language
40
+ - Being respectful of differing viewpoints and experiences
41
+ - Gracefully accepting constructive criticism
42
+ - Focusing on what is best for the community
43
+ - Showing empathy towards other community members
44
+
45
+ Examples of unacceptable behavior by participants include:
46
+
47
+ - The use of sexualized language or imagery and unwelcome sexual attention or advances
48
+ - Trolling, insulting/derogatory comments, and personal or political attacks
49
+ - Public or private harassment
50
+ - Publishing others’ private information, such as a physical or electronic address, without explicit permission
51
+ - Other conduct which could reasonably be considered inappropriate in a professional setting
52
+
53
+ # Our Responsibilities
54
+
55
+ Maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
56
+
57
+ Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
58
+
59
+ # Scope
60
+
61
+ This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
package/README.md CHANGED
@@ -1,13 +1,8 @@
1
- # @aiursoft/uistack-markdown-ui
1
+ # MarkdownUI.js
2
2
 
3
- Shared Markdown UI behavior for Aiursoft applications.
3
+ [![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
4
 
5
- - Secure `markdown-it` rendering with native HTML disabled
6
- - highlight.js 11.11.1 highlighting
7
- - Mermaid 11 enhancement with `securityLevel: "strict"`
8
- - MathJax 3 enhancement and print coordination
9
- - Monaco-compatible paste and drag/drop image upload
10
- - Shared Monaco editor lifecycle, shortcuts, preview, view modes and textarea fallback
5
+ Shared Markdown rendering, editing and reading components.
11
6
 
12
7
  ## Install
13
8
 
@@ -15,137 +10,20 @@ Shared Markdown UI behavior for Aiursoft applications.
15
10
  npm install @aiursoft/uistack-markdown-ui
16
11
  ```
17
12
 
18
- ## Editor preview
13
+ ## Usage
19
14
 
20
15
  ```js
21
- import { renderMarkdown } from "@aiursoft/uistack-markdown-ui";
16
+ import { renderMarkdown } from '@aiursoft/uistack-markdown-ui';
22
17
 
23
- preview.innerHTML = renderMarkdown(editor.getValue());
18
+ preview.innerHTML = renderMarkdown('# Hello');
24
19
  ```
25
20
 
26
- The renderer supports `$...$`, `$$...$$`, `\\(...\\)` and `\\[...\\]`. Native HTML is
27
- always escaped. A fenced `mermaid` block remains unhighlighted for Mermaid to process.
21
+ See [usage and API](docs/usage.md) for editors, readers, image uploads and print integration.
28
22
 
29
- ## Complete Markdown editor
23
+ ## Development
30
24
 
31
- `createMarkdownEditor` owns the common editor behavior while the application remains
32
- responsible for loading Monaco. Passing a loader instead of importing Monaco keeps it
33
- out of application bundles and works with the standard Monaco AMD loader.
34
-
35
- ```js
36
- import { createMarkdownEditor } from "@aiursoft/uistack-markdown-ui";
37
-
38
- const markdownEditor = await createMarkdownEditor({
39
- editorContainer: document.querySelector("#markdown-editor"),
40
- textarea: document.querySelector("#markdown-source"),
41
- previewContainer: document.querySelector("#markdown-preview"),
42
- editorPane: document.querySelector("#editor-pane"),
43
- previewPane: document.querySelector("#preview-pane"),
44
- form: document.querySelector("form"),
45
- loadMonaco: () => AiursoftMarkdownUi.loadMonacoFromAmd(),
46
- theme: "vs-dark",
47
- uploadUrl: "/api/files/upload",
48
- initialViewMode: "split",
49
- viewModeStorageKey: "markdown-view-mode",
50
- viewModeControls: [
51
- { element: document.querySelector("#edit-mode"), mode: "editor" },
52
- { element: document.querySelector("#split-mode"), mode: "split" },
53
- { element: document.querySelector("#preview-mode"), mode: "preview" }
54
- ],
55
- hljs,
56
- mermaid,
57
- MathJax,
58
- onSave: markdown => saveMarkdown(markdown),
59
- onInitializationError: error => console.error("Monaco failed to initialize", error),
60
- onPreviewError: error => console.error("Markdown preview failed", error)
61
- });
62
-
63
- await markdownEditor.setViewMode("preview");
64
- markdownEditor.syncTextarea();
65
- markdownEditor.setValue("# Updated");
66
- markdownEditor.focus();
67
- markdownEditor.dispose();
68
- ```
69
-
70
- The controller initializes Monaco for Markdown, keeps the original textarea synchronized,
71
- debounces secure preview rendering, enhances highlight.js/Mermaid/MathJax, supports image
72
- paste and drop, and applies consistent professional Monaco defaults (14px Cascadia Code
73
- font stack, ligatures, semantic highlighting and comfortable vertical padding). Applications
74
- can still override individual Monaco settings through `editorOptions`.
75
-
76
- It also registers consistent Markdown shortcuts:
77
-
78
- - <kbd>Ctrl/Cmd+B</kbd>: bold
79
- - <kbd>Ctrl/Cmd+I</kbd>: italic
80
- - <kbd>Ctrl/Cmd+K</kbd>: inline or fenced code
81
- - <kbd>Ctrl/Cmd+L</kbd>: link
82
- - <kbd>Ctrl/Cmd+1</kbd> through <kbd>Ctrl/Cmd+6</kbd>: headings
83
- - <kbd>Ctrl/Cmd+S</kbd>: `onSave`
84
- - <kbd>Enter</kbd>: continue bullet and ordered lists
85
-
86
- If Monaco cannot be loaded, the original textarea becomes visible and continues to drive
87
- the same preview. Applications therefore use one fallback policy instead of implementing
88
- their own. Preview enhancement errors are reported through `onPreviewError` and never
89
- replace a working Monaco editor. `onError` remains as a deprecated compatibility callback
90
- for both error categories.
91
-
92
- ## Reading pages
93
-
94
- ```js
95
- import {
96
- initializeMarkdownReader,
97
- printMarkdown
98
- } from "@aiursoft/uistack-markdown-ui";
99
-
100
- await initializeMarkdownReader({
101
- container: ".markdown-body",
102
- hljs,
103
- mermaid,
104
- MathJax
105
- });
106
-
107
- printButton.addEventListener("click", () =>
108
- printMarkdown({ container: ".markdown-body", hljs, mermaid, MathJax }));
109
- ```
110
-
111
- Only code blocks inside the supplied container are highlighted. Mermaid is always
112
- initialized in strict security mode. The reader also applies the shared responsive
113
- Bootstrap table treatment and opens rendered links with `noopener noreferrer`.
114
-
115
- ## Image paste and drop
116
-
117
- ```js
118
- import { attachImageUpload } from "@aiursoft/uistack-markdown-ui";
119
-
120
- const uploads = attachImageUpload({
121
- editor,
122
- eventTarget: editorContainer.parentElement,
123
- uploadUrl: "/api/files/upload",
124
- onError: (error, file) => console.error(`Failed to upload ${file.name}`, error)
125
- });
126
-
127
- // Call uploads.dispose() when the editor is destroyed.
25
+ ```bash
26
+ npm ci
27
+ npm run check
28
+ npm pack
128
29
  ```
129
-
130
- The default queue uploads three files concurrently and retries HTTP 429 responses up
131
- to five times. Clipboard images are accepted from both `clipboardData.files` and
132
- `clipboardData.items`, and are captured before Monaco consumes the paste event. Use
133
- the parent of Monaco's host container as `eventTarget`; `createMarkdownEditor()` does
134
- this automatically. Use `getImageUrl` when an endpoint does not return
135
- `internetPath` or `InternetPath`.
136
-
137
- ## Aiursoft application contract
138
-
139
- MarkToHtml, MoongladeV2, EmployeeCenter and Kanban use the global IIFE build and the
140
- same `createMarkdownEditor` contract. Monaco, live preview, highlight.js, Mermaid,
141
- MathJax, Markdown shortcuts, image paste/drop, editor/split/preview modes and the
142
- textarea fallback are required capabilities for these full editors.
143
-
144
- DocsViewer and HowToCookViewer are reader-only consumers. Their Markdown containers
145
- use `initializeMarkdownReader` for highlighting, Mermaid, MathJax, responsive tables
146
- and safe external-link behavior.
147
-
148
- Translate is an intentional product-level exception. It keeps its lightweight
149
- CodeMirror Markdown input because translation does not need code highlighting,
150
- Mermaid, MathJax, uploads or the full editing toolbar. It must not be treated as an
151
- incomplete migration.
package/docs/usage.md ADDED
@@ -0,0 +1,151 @@
1
+ # @aiursoft/uistack-markdown-ui
2
+
3
+ Shared Markdown UI behavior for Aiursoft applications.
4
+
5
+ - Secure `markdown-it` rendering with native HTML disabled
6
+ - highlight.js 11.11.1 highlighting
7
+ - Mermaid 11 enhancement with `securityLevel: "strict"`
8
+ - MathJax 3 enhancement and print coordination
9
+ - Monaco-compatible paste and drag/drop image upload
10
+ - Shared Monaco editor lifecycle, shortcuts, preview, view modes and textarea fallback
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ npm install @aiursoft/uistack-markdown-ui
16
+ ```
17
+
18
+ ## Editor preview
19
+
20
+ ```js
21
+ import { renderMarkdown } from "@aiursoft/uistack-markdown-ui";
22
+
23
+ preview.innerHTML = renderMarkdown(editor.getValue());
24
+ ```
25
+
26
+ The renderer supports `$...$`, `$$...$$`, `\\(...\\)` and `\\[...\\]`. Native HTML is
27
+ always escaped. A fenced `mermaid` block remains unhighlighted for Mermaid to process.
28
+
29
+ ## Complete Markdown editor
30
+
31
+ `createMarkdownEditor` owns the common editor behavior while the application remains
32
+ responsible for loading Monaco. Passing a loader instead of importing Monaco keeps it
33
+ out of application bundles and works with the standard Monaco AMD loader.
34
+
35
+ ```js
36
+ import { createMarkdownEditor } from "@aiursoft/uistack-markdown-ui";
37
+
38
+ const markdownEditor = await createMarkdownEditor({
39
+ editorContainer: document.querySelector("#markdown-editor"),
40
+ textarea: document.querySelector("#markdown-source"),
41
+ previewContainer: document.querySelector("#markdown-preview"),
42
+ editorPane: document.querySelector("#editor-pane"),
43
+ previewPane: document.querySelector("#preview-pane"),
44
+ form: document.querySelector("form"),
45
+ loadMonaco: () => AiursoftMarkdownUi.loadMonacoFromAmd(),
46
+ theme: "vs-dark",
47
+ uploadUrl: "/api/files/upload",
48
+ initialViewMode: "split",
49
+ viewModeStorageKey: "markdown-view-mode",
50
+ viewModeControls: [
51
+ { element: document.querySelector("#edit-mode"), mode: "editor" },
52
+ { element: document.querySelector("#split-mode"), mode: "split" },
53
+ { element: document.querySelector("#preview-mode"), mode: "preview" }
54
+ ],
55
+ hljs,
56
+ mermaid,
57
+ MathJax,
58
+ onSave: markdown => saveMarkdown(markdown),
59
+ onInitializationError: error => console.error("Monaco failed to initialize", error),
60
+ onPreviewError: error => console.error("Markdown preview failed", error)
61
+ });
62
+
63
+ await markdownEditor.setViewMode("preview");
64
+ markdownEditor.syncTextarea();
65
+ markdownEditor.setValue("# Updated");
66
+ markdownEditor.focus();
67
+ markdownEditor.dispose();
68
+ ```
69
+
70
+ The controller initializes Monaco for Markdown, keeps the original textarea synchronized,
71
+ debounces secure preview rendering, enhances highlight.js/Mermaid/MathJax, supports image
72
+ paste and drop, and applies consistent professional Monaco defaults (14px Cascadia Code
73
+ font stack, ligatures, semantic highlighting and comfortable vertical padding). Applications
74
+ can still override individual Monaco settings through `editorOptions`.
75
+
76
+ It also registers consistent Markdown shortcuts:
77
+
78
+ - <kbd>Ctrl/Cmd+B</kbd>: bold
79
+ - <kbd>Ctrl/Cmd+I</kbd>: italic
80
+ - <kbd>Ctrl/Cmd+K</kbd>: inline or fenced code
81
+ - <kbd>Ctrl/Cmd+L</kbd>: link
82
+ - <kbd>Ctrl/Cmd+1</kbd> through <kbd>Ctrl/Cmd+6</kbd>: headings
83
+ - <kbd>Ctrl/Cmd+S</kbd>: `onSave`
84
+ - <kbd>Enter</kbd>: continue bullet and ordered lists
85
+
86
+ If Monaco cannot be loaded, the original textarea becomes visible and continues to drive
87
+ the same preview. Applications therefore use one fallback policy instead of implementing
88
+ their own. Preview enhancement errors are reported through `onPreviewError` and never
89
+ replace a working Monaco editor. `onError` remains as a deprecated compatibility callback
90
+ for both error categories.
91
+
92
+ ## Reading pages
93
+
94
+ ```js
95
+ import {
96
+ initializeMarkdownReader,
97
+ printMarkdown
98
+ } from "@aiursoft/uistack-markdown-ui";
99
+
100
+ await initializeMarkdownReader({
101
+ container: ".markdown-body",
102
+ hljs,
103
+ mermaid,
104
+ MathJax
105
+ });
106
+
107
+ printButton.addEventListener("click", () =>
108
+ printMarkdown({ container: ".markdown-body", hljs, mermaid, MathJax }));
109
+ ```
110
+
111
+ Only code blocks inside the supplied container are highlighted. Mermaid is always
112
+ initialized in strict security mode. The reader also applies the shared responsive
113
+ Bootstrap table treatment and opens rendered links with `noopener noreferrer`.
114
+
115
+ ## Image paste and drop
116
+
117
+ ```js
118
+ import { attachImageUpload } from "@aiursoft/uistack-markdown-ui";
119
+
120
+ const uploads = attachImageUpload({
121
+ editor,
122
+ eventTarget: editorContainer.parentElement,
123
+ uploadUrl: "/api/files/upload",
124
+ onError: (error, file) => console.error(`Failed to upload ${file.name}`, error)
125
+ });
126
+
127
+ // Call uploads.dispose() when the editor is destroyed.
128
+ ```
129
+
130
+ The default queue uploads three files concurrently and retries HTTP 429 responses up
131
+ to five times. Clipboard images are accepted from both `clipboardData.files` and
132
+ `clipboardData.items`, and are captured before Monaco consumes the paste event. Use
133
+ the parent of Monaco's host container as `eventTarget`; `createMarkdownEditor()` does
134
+ this automatically. Use `getImageUrl` when an endpoint does not return
135
+ `internetPath` or `InternetPath`.
136
+
137
+ ## Aiursoft application contract
138
+
139
+ MarkToHtml, MoongladeV2, EmployeeCenter and Kanban use the global IIFE build and the
140
+ same `createMarkdownEditor` contract. Monaco, live preview, highlight.js, Mermaid,
141
+ MathJax, Markdown shortcuts, image paste/drop, editor/split/preview modes and the
142
+ textarea fallback are required capabilities for these full editors.
143
+
144
+ DocsViewer and HowToCookViewer are reader-only consumers. Their Markdown containers
145
+ use `initializeMarkdownReader` for highlighting, Mermaid, MathJax, responsive tables
146
+ and safe external-link behavior.
147
+
148
+ Translate is an intentional product-level exception. It keeps its lightweight
149
+ CodeMirror Markdown input because translation does not need code highlighting,
150
+ Mermaid, MathJax, uploads or the full editing toolbar. It must not be treated as an
151
+ incomplete migration.
package/package.json CHANGED
@@ -1,12 +1,13 @@
1
1
  {
2
2
  "name": "@aiursoft/uistack-markdown-ui",
3
- "version": "1.2.6",
3
+ "version": "1.2.7",
4
4
  "description": "Shared, secure Markdown editing and reading utilities for Aiursoft applications.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
8
8
  "dist",
9
- "README.md"
9
+ "README.md",
10
+ "docs"
10
11
  ],
11
12
  "main": "./dist/index.cjs",
12
13
  "module": "./dist/index.js",
@@ -48,7 +49,6 @@
48
49
  },
49
50
  "repository": {
50
51
  "type": "git",
51
- "url": "https://gitlab.aiursoft.com/aiursoft/uistack.git",
52
- "directory": "src/Aiursoft.UiStack.MarkdownUi"
52
+ "url": "https://gitlab.aiursoft.com/aiursoft/MarkdownUI.js.git"
53
53
  }
54
54
  }