markupeditor 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Steven G. Harris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+<p align="center">
+    <img alt="The MarkupEditor logo" src="https://github.com/user-attachments/assets/c67b6aa0-2576-4a0b-81d0-229ee501b59d" width="96px" height="96px" >
+</p>
+
+# MarkupEditor
+
+The MarkupEditor consists of a web component and API for WYSIWYG HTML editing. The "source of truth" for the MarkupEditor is standard HTML, 
+styled using standard CSS. The MarkupEditor comes with a toolbar and hot key bindings to access its editing functionality. The toolbar 
+visibility and contents, as well as the key bindings, are configurable and extensible.
+
+![Hello, MarkupEditor!](resources/hellomarkupeditor.png)
+
+The web component makes embedding WYSIWYG editing as simple as:
+
+```
+<markup-editor><h1>Hello, MarkupEditor!</h1></markup-editor>
+<script src="markup-editor.js" type="module"></script>
+```
+
+### Why
+
+You or the consumers of your application need to edit more than just plain text. You want to be able to format and organize a document with 
+headers, lists, links, images, and perhaps tables, but you do not want to do that using Markdown or require that the consumers of your app 
+know anything about Markdown or HTML.  The MarkupEditor is the solution. It can be used in any environment that supports a web view, from a 
+browser to a mobile or desktop app.
+
+Like Markdown, the MarkupEditor keeps the focus on what you're writing, with a minimum of distractions. Like Markdown, it supports just enough 
+functionality to help you organize and format your writing to get your points across effectively. Unlike Markdown, the MarkupEditor's WYSIWYG 
+approach means you always see what you're writing presented properly as you write it, instead of dealing with the distractions of composing 
+text with embedded notations and the uncertainty of how that text is later translated to HTML and presented.
+
+## Features
+
+The MarkupEditor's standard editing features are generally limited to what 
+[Github Flavored Markdown](https://github.github.com/gfm/) supports. It does, however, have support 
+for some functionality beyond that baseline. As a WYSIWYG editor, it supports the kind of functionality that 
+even non-developers expect when they edit a document, like image resizing and search.
+
+* Customizable and extensible toolbar providing access to all editing features, auto-sized to width.
+* Customizable key mappings for hot-key access to editing features.
+* Customizable ordering of toolbar contents.
+* Customizable icons for toolbar.
+* Paragraph styles corresponding to P, H1-H6, and `CODE`.
+* Bold, italic, underline, strikethrough, subscript, superscript, and code text formatting.
+* Insert and edit links, images (local and https src), and tables.
+* Bulleted and numbered lists.
+* Indent/outdent.
+* Comprehensive undo/redo.
+* Search.
+* Image resizing using gestures.
+* Table editing: visually select table size, add/remove row/column/header, border options.
+
+The API provides hooks for callbacks as your document changes, as well as access to the edited HTML 
+so that you can save contents in a way that makes sense in your own context.
+
+The web component and customization capabilities allow the MarkupEditor to be embedded in different 
+environments, such as an Electron-based [desktop editing app](https://github.com/stevengharris/markupeditor-desktop), 
+a [Swift library for WYSIWYG editing](https://github.com/stevengharris/MarkupEditor), and 
+a [VSCode extension](https://github.com/stevengharris/markupeditor-vs).
+
+## Try
+
+You can try the MarkupEditor out right from the [project web site](https://stevengharris.github.io/markupeditor-base/). The web site has all 
+the information you need to use the MarkupEditor in your application.
+
+## Install
+
+Clone the repository.
+
+```
+git clone https://github.com/stevengharris/markupeditor-base.git
+```
+
+You need node/npm installed. Install the dependencies.
+
+```
+$ cd markupeditor-base/
+$ npm install
+
+added 265 packages, and audited 266 packages in 9s
+
+70 packages are looking for funding
+  run `npm fund` for details
+
+found 0 vulnerabilities
+$ 
+```
+
+Build the project.
+
+```
+$ npm run build
+
+> markupeditor@0.9.0 build
+> rollup -c
+
+
+src/main.js → dist/markup-editor.js...
+created dist/markup-editor.js in 300ms
+```
+
+The installation identifies `muedit` in the package.json `bin` property. You can open the editor on a doc using node.js with 
+the `muedit` command, providing a filename to edit (and optionally a port for node.js). You can use the demo.html file that 
+is part of the docs:
+
+```
+$ muedit docs/demo/demo.html 
+Server listening at http://localhost:3000
+```
+
+Then open http://localhost:3000 in your browser. The port can be passed to node as `--port <number>`. Alternatively, you 
+can run node directly as `node ./bin/muedit.js docs/demo/demo.html`.
+
+## Local Documentation
+
+You can also set up the web site docs to test and view locally. The `npm run docs` command copies the `markup-editor.js` 
+file and css (which may have changed locally as you develop) to the proper position in the `docs` directory and then runs
+`jsdoc` to produce the API documentation. The API documentation contents and options are defined in `jsdoc.json` and
+use a customized template, `apilayout.tmpl`. The `apireadme.md` in the `docs/resources` directory is displayed as the 
+contents of the "home" page. 
+
+```
+$ npm run docs
+
+> markupeditor@0.9.0 predocs
+> sh predocs.sh && jsdoc -c jsdoc.json
+
+Updating ./docs dependencies...
+cp -f ./dist/markup-editor.js ./docs/src/markup-editor.js
+cp -f ./styles/markupeditor.css ./docs/styles/markupeditor.css
+cp -f ./styles/markup.css ./docs/styles/markup.css
+cp -f ./styles/mirror.css ./docs/styles/mirror.css
+cp -f ./styles/toolbar.css ./docs/styles/toolbar.css
+
+> markupeditor@0.9.0 docs
+> node ./docs/index.js
+
+Server listening at http://localhost:3000
+```
+
+What http://localhost:3000 shows now is the contents hosted at https://stevengharris.github.io/markupeditor-base.
+
+Since the project web site is hosted on GitHub Pages, this process makes it simple to keep the docs up-to-date and 
+test the web site locally.
+
+## Resources
+
+Refer to the [Resources](https://stevengharris.github.io/markupeditor-base/#resources) section of the [project web site](https://stevengharris.github.io/markupeditor-base/)
+for links to documentation, demos, and other projects using the MarkupEditor.
+
+## Acknowledgements
+
+This project was originally delivered as a single JavaScript file within the [Swift MarkupEditor](https://github.com/stevengharris/MarkupEditor), 
+a project that provides WYSIWYG editing functionality to Swift UIKIt and iOS SwiftUI developers. Eventually, the Swift project moved to using the 
+excellent [ProseMirror](https://prosemirror.net) project for all of the heavy lifting of WYSIWYG editing in its web view backend. With the formalization 
+of this MarkupEditor base project, the Swift project now depends on `markupeditor-base` which in turn depends on ProseMirror. The MarkupEditor base 
+project can then be re-used, within a [desktop editing app](https://github.com/stevengharris/markupeditor-desktop) or 
+[VSCode extension](https://github.com/stevengharris/markupeditor-vs).
+
+To quote from the ProseMirror site:
+
+> ProseMirror is [open source](https://github.com/ProseMirror/prosemirror/blob/master/LICENSE), and you are legally free to use it commercially. Yet, writing, maintaining, supporting, and setting up infrastructure for such a project takes a lot of work and energy. Therefore...
+
+> **If you are using ProseMirror to make profit, there is a social expectation that you help fund its maintenance. [Start here](http://marijnhaverbeke.nl/fund/).**
+
+I encourage MarkupEditor users to take these statements to heart and support ProseMirror directly if you use the MarkupEditor to make a profit.
+
+

package/bin/filetoolbar.css

@@ -0,0 +1,28 @@
+/* Base toast styling */
+.toast {
+    font-size: 1rem;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    display: inline-block;
+    visibility: hidden; /* Hidden by default */
+    background-color: #333; 
+    color: #fff;
+    text-align: center;
+    border-radius: 2px;
+    padding: 4px;
+    margin-bottom: 8px; /* Spacing between multiple toasts */
+    opacity: 0;
+    transition: opacity 0.5s, visibility 0.5s;
+}
+@media (prefers-color-scheme: dark) {
+  .toast {
+    background: #fff;
+    color: #333;
+  }
+}
+
+/* Class added by JavaScript to show the toast */
+.toast.show {
+    visibility: visible;
+    opacity: 1;
+}

package/bin/filetoolbar.js

@@ -0,0 +1,126 @@
+import { MU } from "/markup-editor.js"
+
+/** A class holding the command items and functionality for a File toolbar that is prepended to the MarkupEditor toolbar */
+class FileToolbar {
+    constructor() {
+        this.menuItems = this.buildMenuItems()
+    }
+
+    /** SVG defining icons by key, obtained from https://fonts.google.com/icons under https://openfontlicense.org license. */
+    icons = {
+        // <span class="material-symbols-outlined">note_add</span>
+        new: '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#1f1f1f"><path d="M440-240h80v-120h120v-80H520v-120h-80v120H320v80h120v120ZM240-80q-33 0-56.5-23.5T160-160v-640q0-33 23.5-56.5T240-880h320l240 240v480q0 33-23.5 56.5T720-80H240Zm280-520v-200H240v640h480v-440H520ZM240-800v200-200 640-640Z"/></svg>',
+        // <span class="material-symbols-outlined">file_open</span>
+        open: '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#1f1f1f"><path d="M240-80q-33 0-56.5-23.5T160-160v-640q0-33 23.5-56.5T240-880h320l240 240v240h-80v-200H520v-200H240v640h360v80H240Zm638 15L760-183v89h-80v-226h226v80h-90l118 118-56 57Zm-638-95v-640 640Z"/></svg>',
+        // <span class="material-symbols-outlined">file_copy</span>
+        copy: '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#1f1f1f"><path d="M744-192H312q-29 0-50.5-21.5T240-264v-576q0-29 21.5-50.5T312-912h312l192 192v456q0 29-21.5 50.5T744-192ZM576-672v-168H312v576h432v-408H576ZM168-48q-29 0-50.5-21.5T96-120v-552h72v552h456v72H168Zm144-792v195-195 576-576Z"/></svg>'
+    }
+
+    /** Return an array of MenuItems */
+    buildMenuItems() {
+        let newItem = MU.cmdItem(
+            this.newDocument.bind(this),
+            {
+                enable: () => { return true },
+                title: 'New document',
+                icon: this.icons.new
+            }
+        )
+        let openItem = MU.cmdItem(
+            this.openDocument.bind(this),
+            {
+                enable: () => { return true },
+                title: 'Open document',
+                icon: this.icons.open
+            }
+        )
+        let copyItem = MU.cmdItem(
+            this.copyHTML.bind(this),
+            {
+                enable: () => { return true },
+                title: 'Copy HTML',
+                icon: this.icons.copy,
+                // Use a callback to provide a "toast" indicating the copy worked
+                callback: this.notifyCopy.bind(this)
+            }
+        )
+        return [newItem, openItem, copyItem]
+    }
+
+    newDocument(state, dispatch, view) {
+        MU.setActiveView(view)
+        MU.emptyDocument()
+    }
+
+    /** Open the picker as listen for changes in the input element */
+    openDocument(state, dispatch, view) {
+        MU.setActiveView(view)
+        let picker = document.getElementById('docpicker');
+        picker.addEventListener('change', this.loadDocument.bind(this));
+        picker.showPicker();
+    }
+
+    /** 
+     * When the user selects an HTML file from the picker, get its contents, update the document in 
+     * the editor.
+     * 
+     * Note: Because we don't have access to an actual file picker or any way to determine what local 
+     * directory the file resides in, there is no way to set "base" for the document. This means that 
+     * local images will almost certainly not load and will generate 404s. Refer to the markupeditor-desktop
+     * for an electron example that supports the file system natively.
+     */
+    loadDocument() {
+        let picker = document.getElementById('docpicker');
+        picker.removeEventListener('change', this.loadDocument.bind(this));
+        let files = picker.files;
+        if (files) {
+            let file = files[0]
+            const reader = new FileReader();
+            reader.addEventListener('load', (event) => {
+                const text = event.target.result; // The file contents
+                MU.setHTML(text)
+            });
+            reader.readAsText(file);
+        }
+    }
+
+    async copyHTML(state, dispatch, view) {
+        MU.setActiveView(view)
+        const text = MU.getHTML();
+        try {
+            await navigator.clipboard.writeText(text).then(() => { return })
+        } catch (err) {
+            console.error('Failed to copy: ', err);
+        }
+    }
+
+    /**
+     * Briefly add/remove `toast` class to the `menuItem` to display a "toast" notification.
+     * 
+     * The filetoolbar.css defines the CSS using `userstyle` set in muedit.js.
+     * 
+     * @param {HTMLSpanElement} menuItem 
+     */
+    notifyCopy(_ , menuItem) {
+        const toast = document.createElement("div");
+        toast.classList.add("toast");
+        toast.innerText = "Copied HTML"
+
+        menuItem.appendChild(toast);
+
+        // Show the toast
+        setTimeout(() => {
+            toast.classList.add("show");
+        }, 10); // Small delay to trigger CSS transition/animation
+
+        // Automatically hide and remove the toast after a few seconds
+        setTimeout(() => {
+            toast.classList.remove("show");
+            toast.remove();
+        }, 1500); // Toast visible for 1.5 seconds
+    }
+
+}
+
+/** By registering the augmentation, we can reference it by name in the <markup-editor> element toolbar attribute */
+MU.registerAugmentation(new FileToolbar())

package/bin/muedit.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * A script to run with node.js to open the MarkupEditor on an HTML file (or empty)
+ */
+import {argv} from 'node:process'
+import {parseArgs} from 'node:util'
+import express from 'express'
+import path from 'node:path'
+
+const __dirname = import.meta.dirname
+
+const app = express()
+
+const options = {
+  'port': {
+    type: 'string',
+    default: '3000'
+  }
+}
+
+try {
+  var { values, positionals } = parseArgs({ argv, options, allowPositionals: true })
+} catch {
+  values = []
+  positionals = []
+}
+
+if ((values.length > 1) || (!values.port) || (positionals.length > 1)) {
+  console.log('Usage: muedit [--port number] [<filename>]')
+} else {
+  let port = parseInt(values.port)
+  let filename = (positionals.length > 0) ? positionals[0] : null
+  let filenameAttribute = (filename) ? `filename="${filename}"` : ''          // Empty for a new document
+  // Note that `base` is set to the filename path automatically
+  let placeholder = 'Edit document...'
+
+  // The web component is always located relative to node's `__dirname`,
+  // the location where muedit.js resides, which `app.use(express.static(__dirname))` 
+  // ensures is available no matter what `process.cwd()` is.
+  let webcomponent = `/markup-editor.js`
+  
+  // Allow references to dist from bin to work in index.html, to load the web component
+  app.use(express.static(path.join(__dirname, "../dist")))
+
+  // Allow the userscript and userstyles to load
+  app.use(express.static(__dirname))
+
+  // Allow the relative references inside of the edited document to work
+  app.use(express.static(`${process.cwd()}/`, {index: false}))
+
+  // For parsing application/json
+  app.use(express.json())
+
+  // Load when loading http://localhost:${port}
+  app.get('/', (req, res) => {
+    res.send(
+      `
+      <!DOCTYPE html>
+      <html lang="en">
+        <head>
+          <title>${filename ?? "MarkupEditor"}</title>
+          <meta name="viewport" charset="utf-8" content="width=device-width, initial-scale=1.0">
+        </head>
+        <body>
+          <markup-editor
+            placeholder="${placeholder}"
+            ${filenameAttribute}
+            userscript="/filetoolbar.js"
+            userstyle="/filetoolbar.css"
+            prepend="FileToolbar"
+          >
+          </markup-editor>
+          <input id="docpicker" type="file" accept=".html" style="display: none">
+          <script src="${webcomponent}" type="module"></script>
+        </body>
+      </html>
+    `
+    )
+  })
+
+  app.listen(port, () => {
+    console.log(`Server listening at http://localhost:${port}`)
+  })
+}