lightmetal 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.4.0
+
+- Added six optional CSS skins: Bootstrap, Material Classic, Material Outline,
+  Frost, Patina, and Sterling. Each supports system, light, and dark modes.
+- Build plain and minified skins alongside the unchanged default stylesheet.
+- Added a local skin gallery and browser/package checks for skin appearance,
+  keyboard focus, Source mode, tables, contrast, and narrow layouts.
+
+## 0.3.0
+
+- Added configurable formatting toolbar and custom actions.
+- Added HTML source mode and content access methods.
+- Added image insertion by URL, file picker, paste/drop, base64, and upload hook.
+- Added table insertion and contextual row/column controls.
+- Added system, light, and dark themes.
+- Added import/paste sanitization and normal-mode HTML-drop rejection.
+- Added link/image URL validation and support for base64 JPEG, PNG, GIF, and
+  WebP images in sanitized imports.
+- Added `rawMode` to bypass HTML sanitization while retaining insertion URL
+  and file checks.
+- Added `unrestrictedMode` to bypass HTML, URL, file-type, and file-size checks.
+- Applied `images.enabled` to programmatic image insertion and `allowBase64`
+  to upload results and sanitized imports.
+- Fixed missing-MIME file conversion in standalone and ES module builds.
+- Kept paragraph and CSS formatting settings independent between editor instances.
+- Prevented deferred formatting from changing other editors or running after destroy.
+- Stopped late upload results from scheduling UI updates or image loads after destroy.
+- Validated toolbar actions before registering editor listeners.
+- Fixed content loss from leading closing tags during HTML import.
+- Added per-instance listener cleanup through `destroy()`.
+- Included standalone and ES module bundles with separate CSS.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gunnar
+
+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

@@ -1,3 +1,416 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="ligHTMetaL.png" alt="ligHTMetaL logo" width="320">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# ligHTMetaL
+
+A small HTML editor. Vanilla JavaScript and CSS. Zero runtime dependencies.
+
+- Format text, headings, lists, quotes, and links.
+- Insert images from URLs, files, clipboard, or drag and drop.
+- Create tables and edit rows and columns.
+- Edit HTML source, customize the toolbar, and choose light or dark themes.
+- Keep the browser's native undo and redo.
+
+**Your content belongs to you.** Data sovereignty is a permanent design
+constraint. No accounts, telemetry, analytics, vendor cloud, or automatic
+document uploads. We will not add tracking or send your documents to a vendor
+cloud. The editor runs in your browser. Your application chooses where content
+is saved and whether anything is uploaded.
+
+Browsers still load image URLs you provide, and an upload hook you configure
+can send files to your server. Self-host the assets and use local/base64 images
+for offline use. Unfiltered HTML can also load resources or execute code; see
+[HTML and safety](#html-and-safety).
+
+- [Use without a build](#use-without-a-build)
+- [Use with npm](#use-with-npm)
+- [Content and API](#content-and-api)
+- [Toolbar](#toolbar)
+- [Images](#images)
+- [Tables](#tables)
+- [Themes and styling](#themes-and-styling)
+- [HTML and safety](#html-and-safety)
+- [Development and tests](#development-and-tests)
+
+## Use without a build
+
+Copy `dist/lightmetal.js` and `dist/lightmetal.css` from this repository beside
+your HTML file. No package manager, framework, or server is required:
+
+```html
+<link rel="stylesheet" href="lightmetal.css">
+<script src="lightmetal.js"></script>
+
+<div id="editor" class="lightmetal"></div>
+
+<script>
+  const editor = lightmetal.init({
+    element: document.getElementById("editor"),
+    onChange: (html) => console.log(html)
+  });
+
+  editor.setHTML("<p>Hello, ligHTMetaL!</p>");
+</script>
+```
+
+Use `lightmetal.min.js` and `lightmetal.min.css` for smaller downloads.
+For native browser modules, copy `lightmetal.esm.js` too and replace the scripts
+above with:
+
+```html
+<script type="module">
+  import { init } from "./lightmetal.esm.js";
+  const editor = init({ element: document.getElementById("editor") });
+</script>
+```
+
+Keep the stylesheet and host div. Run module examples over HTTP(S); the
+standalone example also works over `file://`.
+
+## Use with npm
+
+```bash
+npm install lightmetal --ignore-scripts
+```
+
+The package ships ready-built JS and CSS with no runtime dependencies or
+install hooks. With a bundler:
+
+```js
+import { init } from "lightmetal/dist/lightmetal.esm.js";
+import "lightmetal/dist/lightmetal.css";
+
+const editor = init({
+  element: document.getElementById("editor"),
+  onChange: (html) => console.log(html)
+});
+```
+
+Add `<div id="editor" class="lightmetal"></div>` to your page. The editor needs
+a browser DOM; do not initialize it in Node.js or during server-side rendering.
+
+## Content and API
+
+The examples below use the standalone `lightmetal` global. With ES modules,
+import `init` and `exec` instead.
+
+```js
+editor.setHTML("<h2>A fresh start</h2><p>Write something here.</p>");
+const html = editor.getHTML();
+const text = editor.getText();
+// Save or export these values using your application's own code.
+```
+
+`init(options)` returns:
+
+| Member | Purpose |
+| --- | --- |
+| `element` | Host DOM element. |
+| `content` | Contenteditable div. |
+| `source` | HTML source textarea. |
+| `getHTML()` | Current HTML in either visual or source mode. |
+| `setHTML(html)` | Replace content in either mode; sanitize by default and fire `onChange`. |
+| `getText()` | Plain text from the current HTML in either mode. |
+| `insertImage(urlOrFile)` | Insert a URL, data URI, or File/Blob; resolve to a boolean. |
+| `insertTable(rows = 3, columns = 3)` | Insert a table; return a boolean. |
+| `destroy()` | Remove editor-owned UI and listeners; preserve the host and other host content. |
+
+Call `editor.destroy()` when removing an editor. Image and table insertion
+refuse Source mode and destroyed instances. Multiple editors keep their own
+configuration and listeners.
+
+### Options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `element` | Required | Host element; add `class="lightmetal"` for the built-in styles. |
+| `onChange(html)` | None | Receive content updates. Persistence is up to your application. |
+| `actions` | All built-ins | Ordered toolbar action names or objects. |
+| `defaultParagraphSeparator` | `"div"` | Use `"div"` or `"p"` for new paragraphs. |
+| `styleWithCSS` | `false` | Ask native formatting commands to use CSS styles. |
+| `classes` | Built-in names | Override generated class names; supply matching CSS. |
+| `images` | See below | Image insertion settings. |
+| `tables` | See below | Picker size and insertion limits. |
+| `rawMode` | `false` | Bypass HTML import/paste filtering; insertion checks remain. |
+| `unrestrictedMode` | `false` | Also bypass URL, file-type, and file-size checks. Trusted content only. |
+
+## Toolbar
+
+Choose actions and their order:
+
+```js
+const editor = lightmetal.init({
+  element: document.getElementById("editor"),
+  actions: ["bold", "italic", "heading2", "ulist", "link", "image", "table", "source"]
+});
+```
+
+The built-ins are `bold`, `italic`, `underline`, `strikethrough`, `heading1`,
+`heading2`, `paragraph`, `quote`, `olist`, `ulist`, `code`, `line`, `link`,
+`table`, `image`, and `source`. Omit `actions` to show all; use `[]` for no
+main toolbar buttons.
+
+Mix names with objects to customize a built-in or add an action:
+
+```js
+actions: [
+  "bold",
+  { name: "heading2", title: "Section heading" },
+  {
+    icon: "H₃",
+    title: "Heading 3",
+    result: () => lightmetal.exec("formatBlock", "<h3>")
+  },
+  "source"
+]
+```
+
+An optional `state()` function controls the selected appearance. Custom
+`result()` callbacks replace built-in behavior; image/table actions with a
+null or undefined result use their built-in workflow. Invalid actions throw
+`TypeError` before listeners or editor UI are installed. Icons accept HTML:
+only use trusted configuration.
+
+`exec(command, value = null)` wraps native `document.execCommand`. Use it for
+custom editing commands to keep native undo/redo.
+
+Click **Source** to edit HTML and click again to return to visual mode. Changes
+in both modes reach `onChange`. Source edits are not sanitized. Text remains
+exact in the textarea, but browsers may normalize HTML when returning to visual
+mode. Omit `"source"` from `actions` to leave out this button.
+
+## Images
+
+The **Image** button prompts for a URL. Files can also be pasted, dropped, or
+inserted from code. Files stay in the document as base64 unless you supply an
+upload hook:
+
+```js
+await editor.insertImage("/images/photo.png");
+const file = document.querySelector("input[type=file]").files[0];
+if (file) await editor.insertImage(file);
+```
+
+Insertion resolves to `true` on success or `false` on failure; rejected images
+show a toolbar note. JPEG, PNG, GIF, and WebP are supported, with a default
+2 MiB file limit. Missing MIME types fall back to the filename extension.
+These checks do not authenticate file contents.
+
+Pass these settings under `images`:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `enabled` | `true` | Enable image APIs and file insertion. |
+| `allowURL` | `true` | Show a URL prompt; `false` opens a file picker instead. |
+| `allowBase64` | `true` | Allow base64 insertion and base64 sources in sanitized imports. |
+| `dragDrop` | `true` | Handle dropped files. |
+| `paste` | `true` | Handle clipboard image files. |
+| `maxSize` | `2 * 1024 * 1024` | Maximum file size in bytes. |
+| `onInsert` | `null` | Async file hook returning a URL or data URI. |
+
+`allowURL` only changes the toolbar; programmatic URLs and upload results still
+work. These switches do not filter raw/unrestricted HTML or Source edits.
+Base64 images have uneven HTML email support; handle CID attachments in your
+application.
+
+### Upload to your own server
+
+Uploads are opt-in application code, not an editor service. The same hook
+handles picked, dropped, pasted, and programmatically inserted files:
+
+```js
+const editor = lightmetal.init({
+  element: document.getElementById("editor"),
+  images: {
+    allowBase64: false,
+    onInsert: async (file) => {
+      const body = new FormData();
+      body.append("image", file);
+      const response = await fetch("/upload", { method: "POST", body });
+      if (!response.ok) throw new Error("Upload failed");
+      return (await response.json()).url;
+    }
+  }
+});
+```
+
+Your application must provide `/upload` and return `{ "url": "..." }`. URL
+checks also apply to hook results; returning base64 requires `allowBase64: true`.
+Pending uploads do not insert in Source mode or after destruction.
+
+## Tables
+
+Click **Insert table**, choose a grid size, or enter **Columns** and **Rows**.
+The display shows columns × rows; manual fields default to 3, clamped to your
+limits. Arrow keys move through the grid; Enter/Space inserts. Escape or an
+outside click closes the picker.
+
+```js
+editor.insertTable();     // 3 rows, 3 columns
+editor.insertTable(3, 4);  // 3 rows, 4 columns
+```
+
+Insertion uses the current selection, or the end if the selection is outside
+the editor. The picker saves the position before it opens. Focus moves into the
+first cell; a blank paragraph follows the table. Nested insertion is refused.
+
+Pass these positive-integer settings under `tables`:
+
+```js
+tables: {
+  gridColumns: 10,
+  gridRows: 8,
+  maxColumns: 100,
+  maxRows: 1000,
+  maxCells: 10000
+}
+```
+
+These are the defaults. Grid/manual defaults clamp to your limits. Insertion
+limits do not restrict imported tables. Contextual growth has separate fixed
+caps: 1,000 rows, 100 columns, and 10,000 logical cells (rows × columns).
+
+Click a cell to insert or delete rows/columns, or delete the table. Row edits
+stay within the current section; column edits span sections. Tab/Enter work
+on the controls. Added cells are blank and preserve header type/scope without
+duplicating IDs. References to deleted headers are removed. Removing the last
+row or column removes the table. Insertion and edits use native undo/redo.
+
+Sanitized imports preserve captions, sections, column groups, spans, `scope`,
+`headers`, and cell IDs. Single-cell, full-width section headings support row
+edits; column edits from ordinary cells adjust heading spans. Other merged
+cells, rowspans, uneven rows, and nested tables disable structural edits.
+Column groups disable only column edits. Whole-table deletion remains available.
+Use Source for unsupported structures; cell merging and resizing are not built in.
+
+Table presentation comes from editor CSS, not styles added to new table HTML.
+Supply table styles wherever your application publishes the exported content.
+
+## Themes and styling
+
+The editor follows the system theme. Pin it with `lightmetal-dark` or
+`lightmetal-light` on the host; remove both to follow the system again:
+
+```html
+<div id="editor" class="lightmetal lightmetal-dark"></div>
+```
+
+Styles are scoped under `.lightmetal`. Override CSS variables and editor size:
+
+```css
+#editor { --lightmetal-accent: #c05020; }
+#editor .lightmetal-content,
+#editor .lightmetal-sources { height: 240px; }
+```
+
+Toolbar icons use `currentColor` to follow the theme.
+
+### Optional skins
+
+Preview all six skins alongside the default by opening `examples/skins.html`
+from the checkout; it also works over `file://`. With the demo server running,
+visit `http://localhost:5000/skins.html`.
+
+| Skin | Host class | Appearance |
+| --- | --- | --- |
+| Bootstrap | `lightmetal-bootstrap` | Familiar form controls and blue accents. |
+| Material Classic | `lightmetal-material-classic` | Filled toolbar, round buttons, and an accented baseline. |
+| Material Outline | `lightmetal-material-outline` | Outlined frame and active controls. |
+| Frost | `lightmetal-frost` | Spacious layout, cool colors, and lighter icon strokes. |
+| Patina | `lightmetal-patina` | Crisp toolbar chrome with blue accents. |
+| Sterling | `lightmetal-sterling` | Compact, neutral toolbar chrome. |
+
+Load the default CSS first, then the skin. Add one skin class to the host:
+
+```html
+<link rel="stylesheet" href="dist/lightmetal.css">
+<link rel="stylesheet" href="dist/skins/frost.min.css">
+<div id="editor" class="lightmetal lightmetal-frost"></div>
+```
+
+Initialize the editor as usual. Both plain and minified skin files are built
+from `src/skins/` into `dist/skins/`. Each skin supports the same system,
+`lightmetal-light`, and `lightmetal-dark` modes as the default. Different skins
+can coexist on one page. Skins add no JavaScript, frameworks, fonts, or external
+requests; they use the editor's existing icons.
+
+All skins are original ligHTMetaL CSS. Bootstrap and Material describe the
+design inspiration, not dependencies or affiliations. The default appearance stays unchanged if you load no skin.
+
+## HTML and safety
+
+**Validate and sanitize HTML in your application before rendering or publishing
+it, including on the server.** The editor's small import filter is not a safety
+guarantee and does not filter live typing or Source edits.
+
+| Mode | HTML paste and `setHTML()` | HTML drops | Link/image insertion and files |
+| --- | --- | --- | --- |
+| Normal (default) | DOMParser allowlist filter | Rejected | URL, type, and size checks |
+| `rawMode: true` | Unfiltered | Native browser behavior | Checks remain |
+| `unrestrictedMode: true` | Unfiltered | Native browser behavior | URL, type, and size checks bypassed |
+
+Normal imports remove scripts/styles with their contents, strip handlers,
+styles, and classes, and unwrap unknown elements while cleaning their children.
+HTML drops are rejected regardless of image settings; use paste for filtered
+rich-text import. Plain-text paste uses native editing.
+
+In normal/raw mode, link insertion allows HTTP(S), relative URLs resolving to
+HTTP(S), and `mailto:`. Image insertion allows HTTP(S), relative HTTP(S), and
+syntactically valid base64 JPEG/PNG/GIF/WebP data URIs when enabled. Normal
+imports use the same URL policy. SVG data URIs and other schemes are rejected.
+Relative URLs under `file://` do not resolve to HTTP(S).
+
+Remote images can reveal your IP and make tracking requests; the editor does
+not enforce an origin allowlist. Local/base64 images need no remote image host.
+
+Use raw mode only when your application handles the imported HTML's safety.
+**Unrestricted mode and unfiltered HTML can execute code in your application.**
+Unrestricted mode includes raw mode's bypass; there is no need to enable both.
+Explicit image switches, attribute escaping, table limits, and insertion guards
+still apply to their own workflows. Browsers may normalize or refuse markup;
+unrestricted does not mean every script will execute. Keep untrusted input out
+of these bypass paths, including Source mode.
+
+## Browser support
+
+Tested in Chromium and Firefox. Safari is not covered yet. The editor deliberately
+uses deprecated `document.execCommand` to preserve native editing and undo/redo.
+Browser-generated HTML can differ.
+
+## Development and tests
+
+The browser library has no dependencies. Building uses Node.js/npm, Bash, and
+esbuild; the optional demo server uses Python 3.14+, uv, and Flask:
+
+```bash
+npm ci
+uv sync --frozen
+npm run build
+uv run python examples/server.py
+```
+
+Open `http://localhost:5000/`, or open `examples/index.html` directly with the
+tracked bundles. The demo has default, custom-hook, and raw editors plus a
+shared theme toggle. Its custom hook returns a local data URI; it uploads nothing.
+Python/Flask are not needed to use the editor in your application.
+
+Tests use a global Playwright installation and its Chromium/Firefox browsers:
+
+```bash
+npm install --global playwright
+playwright install chromium firefox
+npm test
+npm run test:package
+```
+
+`npm test` rebuilds bundles, runs browser/security checks in both browsers, and
+checks the standalone demo over `file://` in Chromium. After building,
+`npm run test:security` runs just security regressions. `npm run test:package`
+packs and installs the package with scripts disabled, then checks standalone,
+minified, ESM, and bundled use. It publishes nothing. Keep rebuilt `dist/` files
+with source changes.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Inspired by [Pell](https://github.com/jaredreich/pell).