overtype 2.3.9 → 2.4.0

package/README.md

@@ -1,6 +1,6 @@
 # OverType
 
-A lightweight markdown editor library with perfect WYSIWYG alignment using an invisible textarea overlay technique. Includes optional toolbar. ~110KB minified with all features.
+A lightweight markdown editor library with perfect WYSIWYG alignment using an invisible textarea overlay technique. Includes optional toolbar. ~117KB minified with all features.
 
 ## Live Examples
 
@@ -19,7 +19,7 @@ A lightweight markdown editor library with perfect WYSIWYG alignment using an in
 - ⌨️ **Keyboard shortcuts** - Common markdown shortcuts (Cmd/Ctrl+B for bold, etc.)
 - 📱 **Mobile optimized** - Responsive design with mobile-specific styles
 - 🔄 **DOM persistence aware** - Recovers from existing DOM (perfect for HyperClay and similar platforms)
-- 🚀 **Lightweight** - ~110KB minified
+- 🚀 **Lightweight** - ~117KB minified
 - 🎯 **Optional toolbar** - Clean, minimal toolbar with all essential formatting
 - ✨ **Smart shortcuts** - Keyboard shortcuts with selection preservation
 - 📝 **Smart list continuation** - GitHub-style automatic list continuation on Enter
@@ -35,7 +35,7 @@ We overlap an invisible textarea on top of styled output, giving the illusion of
 
 | Feature | OverType | HyperMD | Milkdown | TUI Editor | EasyMDE |
 |---------|----------|---------|----------|------------|---------|
-| **Size** | ~110KB | 364.02 KB | 344.51 KB | 560.99 KB | 323.69 KB |
+| **Size** | ~117KB | 364.02 KB | 344.51 KB | 560.99 KB | 323.69 KB |
 | **Dependencies** | Bundled | CodeMirror | ProseMirror + plugins | Multiple libs | CodeMirror |
 | **Setup** | Single file | Complex config | Build step required | Complex config | Moderate |
 | **Approach** | Invisible textarea | ContentEditable | ContentEditable | ContentEditable | CodeMirror |
@@ -62,14 +62,42 @@ We overlap an invisible textarea on top of styled output, giving the illusion of
 
 ## Installation
 
-### NPM
+### NPM (bundlers: Vite, webpack, Rollup, etc.)
 ```bash
 npm install overtype
 ```
 
-### CDN
+```javascript
+import OverType from 'overtype';
+
+const [editor] = new OverType('#editor', { value: '# Hello' });
+```
+
+OverType is ESM-first and also ships a CommonJS build, so both styles work:
+
+```javascript
+// ESM — default or named import
+import OverType from 'overtype';
+import { OverType } from 'overtype';
+
+// CommonJS
+const { OverType } = require('overtype');
+```
+
+### CDN: native ES module (no build step)
+```html
+<script type="module">
+  import OverType from 'https://cdn.jsdelivr.net/npm/overtype@latest/dist/overtype.esm.js';
+  const [editor] = new OverType('#editor', { value: '# Hello' });
+</script>
+```
+
+### CDN: global script tag (IIFE)
 ```html
 <script src="https://cdn.jsdelivr.net/npm/overtype@latest/dist/overtype.min.js"></script>
+<script>
+  const [editor] = new OverType('#editor', { value: '# Hello' });
+</script>
 ```
 
 ## Quick Start
@@ -145,6 +173,38 @@ const [editor] = new OverType('#editor', {
 // orderedList, taskList, quote, separator, viewMode
 ```
 
+Custom buttons that behave like toggle buttons can provide `isActive`. When it returns `true` or `false`, OverType updates the button’s `active` class and `aria-pressed` state:
+
+```javascript
+{
+  name: 'customToggle',
+  icon: '<svg>...</svg>',
+  title: 'Custom Toggle',
+  isActive: ({ editor, activeFormats }) => activeFormats.includes('bold'),
+  action: ({ editor }) => {
+    // Toggle your custom formatting
+  }
+}
+```
+
+**Driving formatting from your own UI:**
+
+OverType re-exports the bundled `markdown-actions` library so you can build a fully custom toolbar (or any UI) without installing or bundling `markdown-actions` separately:
+
+```javascript
+import OverType, { markdownActions } from 'overtype';
+
+const [editor] = new OverType('#editor');
+
+// Apply formatting to the editor's textarea directly
+document.querySelector('#bold-btn').addEventListener('click', () => {
+  markdownActions.toggleBold(editor.textarea);
+  editor.textarea.focus();
+});
+```
+
+Available actions include `toggleBold`, `toggleItalic`, `toggleCode`, `insertLink`, `toggleBulletList`, `toggleNumberedList`, `toggleQuote`, `toggleTaskList`, `insertHeader`, `toggleH1`/`H2`/`H3`, `getActiveFormats`, `hasFormat`, `expandSelection`, and `applyCustomFormat`. The same namespace is available as `window.markdownActions` and `OverType.markdownActions` in script-tag builds.
+
 See [examples/custom-toolbar.html](examples/custom-toolbar.html) for complete examples.
 
 ### View Modes
@@ -198,8 +258,12 @@ The toolbar and keyboard shortcuts work together seamlessly:
 - **Cmd/Ctrl + K** - Insert link
 - **Cmd/Ctrl + Shift + 7** - Numbered list
 - **Cmd/Ctrl + Shift + 8** - Bullet list
+- **Cmd/Ctrl + ]** - Indent current line or selection
+- **Cmd/Ctrl + [** - Outdent current line or selection
+- **Tab / Shift+Tab** - Indent or outdent selected lines
 
-All shortcuts preserve text selection, allowing you to apply multiple formats quickly.
+Collapsed **Tab** and **Shift+Tab** follow normal browser focus navigation so keyboard users can leave the editor.
+Editing shortcuts preserve text selection, allowing you to apply multiple formats quickly.
 
 ### Multiple Editors
 
@@ -236,6 +300,38 @@ document.querySelector('form').addEventListener('submit', (e) => {
 });
 ```
 
+### File Uploads
+
+OverType handles paste and drop of files when `fileUpload` is configured. You upload to your own backend in `onInsertFile` and return the markdown to insert. When that markdown link is later removed from the editor, `onRemoveFile` fires so you can clean up the backend file.
+
+```javascript
+const [editor] = new OverType('#editor', {
+  fileUpload: {
+    enabled: true,
+    maxSize: 10 * 1024 * 1024,                  // 10MB
+    mimeTypes: ['image/png', 'image/jpeg'],     // optional whitelist; empty = accept all
+    batch: false,                               // true = one onInsertFile call per drop
+
+    // Upload to your backend, return the markdown link to insert
+    onInsertFile: async (file) => {
+      const { url } = await uploadToBackend(file);
+      const isImage = file.type.startsWith('image/');
+      return isImage ? `![${file.name}](${url})` : `[${file.name}](${url})`;
+    },
+
+    // Optional: fires when an inserted link is removed from the editor.
+    // Useful for deleting orphaned files from storage.
+    onRemoveFile: ({ url, filename, file }) => {
+      fetch(`/api/files/${encodeURIComponent(url)}`, { method: 'DELETE' });
+    }
+  }
+});
+```
+
+`onRemoveFile` only fires for URLs that OverType originally inserted via `onInsertFile`. URL edits, manual paste of an existing link, or programmatic edits to non-tracked URLs do not trigger it.
+
+See [examples/file-upload.html](website/examples/file-upload.html) for a complete working demo.
+
 ### Custom Theme
 
 ```javascript
@@ -468,6 +564,9 @@ new OverType(target, options)
   // Spellcheck
   spellcheck: false,      // Enable browser spellcheck (disabled by default)
 
+  // Link tooltip
+  transformLinkUrl: (url) => url,  // Rewrite the URL shown/opened in the link tooltip (per instance)
+
   // Stats bar
   showStats: false,       // Enable/disable stats bar
   statsFormatter: (stats) => {  // Custom stats format
@@ -476,7 +575,19 @@ new OverType(target, options)
   
   // Callbacks
   onChange: (value, instance) => {},
-  onKeydown: (event, instance) => {}
+  onKeydown: (event, instance) => {},
+  onFocus: (event, instance) => {},
+  onBlur: (event, instance) => {},
+
+  // File upload (paste/drop) — see "File Uploads" section below
+  fileUpload: {
+    enabled: true,
+    maxSize: 10 * 1024 * 1024,                            // bytes (default 10MB)
+    mimeTypes: [],                                        // empty = accept all
+    batch: false,                                         // single onInsertFile call per drop
+    onInsertFile: async (file) => `[${file.name}](url)`,  // required: return inserted markdown
+    onRemoveFile: ({ url, filename, file }) => {}         // fires when an inserted link is removed
+  }
 }
 ```
 
@@ -554,10 +665,12 @@ OverType.init(target, options)
 
 // Initialize with per-element config via data-ot-* attributes
 // Uses kebab-case: data-ot-show-stats="true" → showStats: true
+// Accepts a selector, Element, NodeList, or Array of elements
 OverType.initFromData('.editor', { /* defaults */ })
 
-// Get instance from element
-OverType.getInstance(element)
+// Get instance from a selector, Element, NodeList, or Array
+// Returns the instance for the first matching element
+OverType.getInstance(target)
 
 // Destroy all instances
 OverType.destroyAll()
@@ -573,10 +686,14 @@ OverType.themes.cave
 |----------|--------|
 | Cmd/Ctrl + B | Toggle bold |
 | Cmd/Ctrl + I | Toggle italic |
-| Cmd/Ctrl + K | Wrap in code |
-| Cmd/Ctrl + Shift + K | Insert link |
+| Cmd/Ctrl + K | Insert link |
 | Cmd/Ctrl + Shift + 7 | Toggle numbered list |
 | Cmd/Ctrl + Shift + 8 | Toggle bullet list |
+| Cmd/Ctrl + ] | Indent current line or selection |
+| Cmd/Ctrl + [ | Outdent current line or selection |
+| Tab / Shift+Tab | Indent or outdent selected lines |
+
+When no text is selected, Tab and Shift+Tab use normal browser focus navigation.
 
 ## Supported Markdown
 
@@ -697,6 +814,26 @@ Links are clickable with Cmd/Ctrl+Click only. Direct clicking would interfere wi
 
 These limitations are what enable OverType's core benefits: perfect native textarea behavior, tiny size, and zero complexity.
 
+## Transforming Link URLs
+
+When your cursor is inside a `[text](url)`, OverType shows a tooltip to open the link. If you edit a document at a different path or domain than where it's published, relative URLs can point to the wrong place. Pass `transformLinkUrl` to rewrite the URL shown and opened by the tooltip, per instance. Your markdown text and the rendered preview are left untouched.
+
+```javascript
+const urlPreviewRegExp = [[/^\//, '/preview/'], [/www\./, '']];
+
+const [editor] = new OverType('#editor', {
+  transformLinkUrl: (url) => urlPreviewRegExp.reduce((value, re) => value.replace(...re), url)
+});
+```
+
+The transformed URL is passed through OverType's URL sanitizer before opening, so the tooltip can never open a dangerous scheme (`javascript:`, `data:`, and similar). If your function throws or returns a non-string, the original URL is used.
+
+## Recipes
+
+OverType stays small by leaving optional features to the host app and exposing the public API needed to build them (`editor.textarea`, `onChange`, `getValue`/`setValue`).
+
+- **[Autocomplete / mention popups](docs/AUTOCOMPLETE.md)** - GitHub-style `@mention` and `#issue` popups built entirely on the public API, no core changes.
+
 ## Development
 
 ```bash
@@ -761,9 +898,25 @@ Use `OverType.initFromData()` to configure multiple editors via HTML data attrib
 
 Uses kebab-case attributes that convert to camelCase options (e.g., `data-ot-show-stats` → `showStats`).
 
-**Supported:** `toolbar`, `theme`, `value`, `placeholder`, `autofocus`, `auto-resize`, `min-height`, `max-height`, `font-size`, `line-height`, `show-stats`, `smart-lists`, `show-active-line-raw`
+### Native textarea attributes (`required`, `name`, etc.)
+
+Set `textareaProps` from HTML in two ways:
+
+```html
+<!-- One attribute per prop: data-ot-textarea-<attr> -->
+<div class="editor" data-ot-textarea-required data-ot-textarea-name="message"></div>
+
+<!-- Or the whole object as JSON -->
+<div class="editor" data-ot-textarea-props='{"required":true,"maxLength":500,"name":"message"}'></div>
+```
+
+Both put a real `required`/`name`/etc. attribute on the underlying `<textarea>`, so the editor participates in native form validation. To make a field optional, omit the attribute (don't set `data-ot-textarea-required="false"`, which still marks it required, the same way the HTML `required` attribute works).
+
+Any object-valued option can also be passed as JSON (values starting with `{` or `[` are parsed; malformed JSON falls back to the raw string).
+
+**Supported:** `toolbar`, `theme`, `value`, `placeholder`, `autofocus`, `auto-resize`, `min-height`, `max-height`, `font-size`, `line-height`, `show-stats`, `smart-lists`, `show-active-line-raw`, `textarea-props` / `textarea-*`
 
-**Not supported (use JS):** `toolbarButtons`, `textareaProps`, `onChange`, `onKeydown`, `statsFormatter`, `codeHighlighter`, `colors`, `mobile`
+**Not supported (use JS):** `toolbarButtons`, `onChange`, `onKeydown`, `onFocus`, `onBlur`, `statsFormatter`, `codeHighlighter`, `colors`, `mobile`
 
 ## Contributors
 
@@ -776,7 +929,7 @@ Special thanks to:
 - [Lyric Wai](https://github.com/lyricat) - Fixed double-escaping of links ([#64](https://github.com/panphora/overtype/pull/64)), shared code block alignment fix ([#65](https://github.com/panphora/overtype/issues/65))
 - [kozi](https://github.com/kozi) - Reported Firefox link tooltip bug ([#68](https://github.com/panphora/overtype/issues/68)), toolbar positioning ([#69](https://github.com/panphora/overtype/issues/69)), theme CSS variable issues ([#70](https://github.com/panphora/overtype/issues/70), [#71](https://github.com/panphora/overtype/issues/71))
 - [1951FDG](https://github.com/1951FDG) - Reported unordered list rendering bug ([#74](https://github.com/panphora/overtype/issues/74)), suggested showStats() API improvement ([#77](https://github.com/panphora/overtype/issues/77)), reported placeholder CSS regression ([#102](https://github.com/panphora/overtype/issues/102))
-- [nodesocket](https://github.com/nodesocket) - Reported toolbarButtons export issues ([#73](https://github.com/panphora/overtype/issues/73), [#78](https://github.com/panphora/overtype/issues/78)), suggested image toolbar button ([#89](https://github.com/panphora/overtype/issues/89)), reported custom theme stats bar styling ([#101](https://github.com/panphora/overtype/issues/101))
+- [nodesocket](https://github.com/nodesocket) - Reported toolbarButtons export issues ([#73](https://github.com/panphora/overtype/issues/73), [#78](https://github.com/panphora/overtype/issues/78)), suggested image toolbar button ([#89](https://github.com/panphora/overtype/issues/89)), reported custom theme stats bar styling ([#101](https://github.com/panphora/overtype/issues/101)), suggested onRemoveFile callback ([#104](https://github.com/panphora/overtype/issues/104))
 - [Travis Bell](https://github.com/travisbell) - Reported keyboard shortcuts bug in ESM build ([#80](https://github.com/panphora/overtype/issues/80))
 - [fab2713](https://github.com/fab2713) - Reported italic rendering in lists ([#81](https://github.com/panphora/overtype/issues/81)), reinit maxHeight ([#82](https://github.com/panphora/overtype/issues/82)), placeholder visibility ([#83](https://github.com/panphora/overtype/issues/83)), suggested auto theme ([#84](https://github.com/panphora/overtype/issues/84)), relative URL prefix ([#85](https://github.com/panphora/overtype/issues/85)), minification improvements ([#94](https://github.com/panphora/overtype/issues/94))
 - [oooo-ps](https://github.com/oooo-ps) - Reported remote script loading issue ([#86](https://github.com/panphora/overtype/issues/86))
@@ -789,6 +942,9 @@ Special thanks to:
 - [phinnaeus](https://github.com/phinnaeus) - Diagnosed missing fontFamily wiring ([#110](https://github.com/panphora/overtype/issues/110))
 - [Tan Nhu](https://github.com/tnhu) - Fixed onChange feedback loop with async syntax highlighters ([#111](https://github.com/panphora/overtype/pull/111))
 - [pscanf](https://github.com/pscanf) - Re-exported markdown-actions for custom toolbar implementations ([#105](https://github.com/panphora/overtype/issues/105), [#106](https://github.com/panphora/overtype/pull/106))
+- [riasvdv](https://github.com/riasvdv) - Contributed keyboard focus-trap fix ([#115](https://github.com/panphora/overtype/pull/115)) and toolbar accessibility following the W3C APG Toolbar pattern ([#114](https://github.com/panphora/overtype/pull/114))
+- [gcamacho079](https://github.com/gcamacho079) - Reported the markdown editor keyboard focus trap ([#113](https://github.com/panphora/overtype/issues/113))
+- [Matt Round](https://mattround.com/) - Reported the Safari stale-glyph caret/wrap desync and supplied the original workaround ([#116](https://github.com/panphora/overtype/issues/116))
 
 ### TypeScript & Framework Support
 - [merlinz01](https://github.com/merlinz01) - Contributed TypeScript declaration file ([#20](https://github.com/panphora/overtype/pull/20))
@@ -800,7 +956,7 @@ Special thanks to:
 - [Yukai Huang](https://github.com/Yukaii) - Contributed syntax highlighting implementation ([#35](https://github.com/panphora/overtype/pull/35))
 - [Rognoni](https://github.com/rognoni) - Suggested custom toolbar button API ([#61](https://github.com/panphora/overtype/issues/61))
 - [Deyan Gigov](https://github.com/dido739) - Reported checkbox rendering bug in preview mode ([#60](https://github.com/panphora/overtype/issues/60)), contributed auto theme implementation ([#100](https://github.com/panphora/overtype/pull/100))
-- [GregJohnStewart](https://github.com/GregJohnStewart) - Suggested data attribute configuration ([#76](https://github.com/panphora/overtype/issues/76)), reported initFromData array nesting bug ([#93](https://github.com/panphora/overtype/issues/93)), suggested DOM element init ([#92](https://github.com/panphora/overtype/issues/92))
+- [GregJohnStewart](https://github.com/GregJohnStewart) - Suggested data attribute configuration ([#76](https://github.com/panphora/overtype/issues/76)), reported initFromData array nesting bug ([#93](https://github.com/panphora/overtype/issues/93)), suggested DOM element init ([#92](https://github.com/panphora/overtype/issues/92)), suggested supporting more options via data attributes ([#112](https://github.com/panphora/overtype/issues/112))
 - [boris-glumpler](https://github.com/boris-glumpler) - Suggested custom syntax highlighting API ([#79](https://github.com/panphora/overtype/issues/79))
 - [sorokya](https://github.com/sorokya) - Contributed file upload support ([#87](https://github.com/panphora/overtype/pull/87))
 - [aaronmyatt](https://github.com/aaronmyatt) - Contributed show/hide toolbar methods ([#95](https://github.com/panphora/overtype/pull/95))