@livingdocs/editable.js 5.1.12 → 5.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@livingdocs/editable.js",
   "description": "Friendly contenteditable API",
-  "version": "5.1.12",
+  "version": "5.2.0",
   "dependencies": {
     "lodash-es": "^4.17.21"
   },
@@ -85,11 +85,11 @@
     "isCi": true,
     "name": "Drone",
     "service": "drone",
-    "commit": "f7175e19d3bfe844d093c6dff8474e25dd64605c",
-    "build": "2997",
+    "commit": "eaa44590d0a4d805673d01538fe45aaa69662513",
+    "build": "3076",
     "branch": "master",
     "isPr": false,
     "slug": "livingdocsIO/editable.js",
-    "date": "2026-09-01T07:26:36.322Z"
+    "date": "2026-09-21T14:33:07.329Z"
   }
 }

package/src/content.js

@@ -2,6 +2,7 @@ import * as nodeType from './node-type.js'
 import * as rangeSaveRestore from './range-save-restore.js'
 import * as parser from './parser.js'
 import * as string from './util/string.js'
+import {refreshCssHighlights} from './plugins/highlighting/css-highlights.js'
 import {createElement, createRange, getNodes, normalizeBoundaries, splitBoundaries, containsNodeText} from './util/dom.js'
 import config from './config.js'
 
@@ -78,6 +79,7 @@ export function cleanInternals (element) {
   // Uses extract content for simplicity. A custom method
   // that does not clone the element could be faster if needed.
   element.innerHTML = extractContent(element, true)
+  refreshCssHighlights({editableHost: element})
 }
 
 // Extracts the content from a host element.
@@ -343,6 +345,7 @@ export function forceWrap (host, range, elem) {
   }
 
   wrap(restoredRange, elem)
+  refreshCssHighlights({editableHost: host})
   return restoredRange
 }
 
@@ -364,15 +367,19 @@ export function unwrap (elem) {
 }
 
 export function removeFormattingElem (host, range, elem) {
-  return restoreRange(host, range, () => {
+  const restoredRange = restoreRange(host, range, () => {
     nukeElem(host, range, elem)
   })
+  refreshCssHighlights({editableHost: host})
+  return restoredRange
 }
 
 export function removeFormatting (host, range, selector) {
-  return restoreRange(host, range, () => {
+  const restoredRange = restoreRange(host, range, () => {
     nuke(host, range, selector)
   })
+  refreshCssHighlights({editableHost: host})
+  return restoredRange
 }
 
 // Unwrap all tags this range is affected by.

package/src/core.js

@@ -8,6 +8,15 @@ import Dispatcher from './dispatcher.js'
 import Cursor from './cursor.js'
 import highlightSupport from './highlight-support.js'
 import MonitoredHighlighting from './monitored-highlighting.js'
+import Selection from './selection.js'
+import {
+  getCssHighlightText,
+  setCssHighlight,
+  deleteCssHighlight,
+  createCssHighlightRange,
+  getCssHighlightRects,
+  getCssHighlightTextOffset
+} from './plugins/highlighting/css-highlights.js'
 import createDefaultEvents from './create-default-events.js'
 import {textNodesUnder, getTextNodeAndRelativeOffset} from './util/element.js'
 import {binaryCursorSearch} from './util/binary_search.js'
@@ -428,6 +437,80 @@ export class Editable {
     highlightSupport.updateHighlight(editableHost, highlightId, addCssClass, removeCssClass)
   }
 
+  /**
+   * @param  {Object} options
+   * @param  {DOMNode} options.editableHost
+   * @return {String}
+   */
+  getCssHighlightText ({editableHost}) {
+    return getCssHighlightText({editableHost})
+  }
+
+  /**
+   * @param {Object} options
+   * @param {String} options.name
+   * @param {Array} [options.ranges]
+   * @param {DOMNode} options.ranges[].editableHost
+   * @param {Number} options.ranges[].start
+   * @param {Number} options.ranges[].end
+   */
+  setCssHighlight ({name, ranges = []}) {
+    setCssHighlight({name, ranges, win: this.win})
+  }
+
+  /**
+   * @param {Object} options
+   * @param {String} options.name
+   */
+  deleteCssHighlight ({name}) {
+    deleteCssHighlight({name, win: this.win})
+  }
+
+  /**
+   * @param {Object} options
+   * @param {DOMNode} options.editableHost
+   * @param {Number} options.start
+   * @param {Number} options.end
+   * @param {String} options.text
+   * @return {Boolean}
+   */
+  replaceCssHighlight ({editableHost, start, end, text}) {
+    const range = createCssHighlightRange({editableHost, start, end, win: this.win})
+    if (!range) return false
+
+    const cursor = new Selection(editableHost, range).insertCharacter(text)
+    cursor.triggerChange()
+    return true
+  }
+
+  /**
+   * @param {Object} options
+   * @param {DOMNode} options.editableHost
+   * @param {Number} options.start
+   * @param {Number} options.end
+   * @return {Object|undefined}
+   */
+  getCssHighlightRects ({editableHost, start, end}) {
+    return getCssHighlightRects({editableHost, start, end, win: this.win})
+  }
+
+  /**
+   * @param  {Object} options
+   * @param  {DOMNode} options.editableHost
+   * @return {Number|undefined}
+   */
+  getCssHighlightCursorOffset ({editableHost}) {
+    const cursor = this.getSelection(editableHost)
+    if (!cursor?.isCursor) return
+
+    const {startContainer, startOffset} = cursor.range
+    return getCssHighlightTextOffset({
+      editableHost,
+      container: startContainer,
+      containerOffset: startOffset
+    })
+  }
+
   /**
    * Subscribe a callback function to a custom event fired by the API.
    *

package/src/highlight-support.js

@@ -1,5 +1,6 @@
 import * as content from './content.js'
 import highlightText from './highlight-text.js'
+import {refreshCssHighlights} from './plugins/highlighting/css-highlights.js'
 import {searchText} from './plugins/highlighting/text-search.js'
 import {createElement, createRange, toCharacterRange} from './util/dom.js'
 
@@ -19,6 +20,7 @@ const highlightSupport = {
     if (matches && matches.length) {
       if (highlightId) matches[0].id = highlightId
       highlightText.highlightMatches(editableHost, matches)
+      refreshCssHighlights({editableHost})
       if (dispatcher) dispatcher.notify('change', editableHost)
       return matches[0].startIndex
     }
@@ -61,6 +63,8 @@ const highlightSupport = {
       marker
     }], false)
 
+    refreshCssHighlights({editableHost})
+
     if (dispatcher) dispatcher.notify('change', editableHost)
 
     return startIndex
@@ -85,6 +89,8 @@ const highlightSupport = {
     // remove empty text nodes, combine adjacent text nodes
     editableHost.normalize()
 
+    refreshCssHighlights({editableHost})
+
     if (dispatcher) dispatcher.notify('change', editableHost)
   },
 

package/src/plugins/highlighting/css-highlights.js

@@ -0,0 +1,359 @@
+import NodeIterator from '../../node-iterator.js'
+import * as nodeType from '../../node-type.js'
+import {createRange} from '../../util/dom.js'
+import {getScrollPosition} from '../../util/viewport.js'
+
+// The DOM ranges in CSS.highlights do not survive markup changes, so keep the
+// character offsets and redraw from those. One registry per window, because
+// this module is shared by every editable on the page while CSS.highlights is
+// not.
+//
+// win -> Map(name -> Map(editableHost -> [{start, end}]))
+const registries = new WeakMap()
+
+// Characters the editable inserts and strips again by itself, so an offset
+// counted with one of them in it would move as soon as it goes.
+const internalCharacters = /[\uFEFF\u200B]/g
+
+const isInternal = (character) => character === '\uFEFF' || character === '\u200B'
+
+const hasInternal = (data) => data.indexOf('\uFEFF') >= 0 || data.indexOf('\u200B') >= 0
+
+const stripInternal = (data) => (hasInternal(data) ? data.replace(internalCharacters, '') : data)
+
+/**
+ * Read an editable as plain text. Callers work in character offsets, so they
+ * need the text those offsets count against.
+ *
+ * @param  {Object} options
+ * @param  {DOMNode} options.editableHost
+ * @return {String}
+ */
+export function getCssHighlightText ({editableHost}) {
+  return readEditable(editableHost).text
+}
+
+/**
+ * Highlight parts of an editable without touching its content. Spell errors
+ * are not part of the document, so they must not end up in the DOM.
+ *
+ * Each call replaces everything held under that name. The offsets are kept so
+ * the highlight can be drawn again after someone else changes the markup.
+ * Passing no ranges removes the highlight.
+ *
+ * @param  {Object} options
+ * @param  {String} options.name
+ * @param  {Array} [options.ranges]
+ * @param  {DOMNode} options.ranges[].editableHost
+ * @param  {Number} options.ranges[].start
+ * @param  {Number} options.ranges[].end
+ * @param  {Window} [options.win]
+ */
+export function setCssHighlight ({name, ranges = [], win = window}) {
+  const hosts = new Map()
+  for (const {editableHost, start, end} of ranges) {
+    const offsets = hosts.get(editableHost)
+    if (offsets) offsets.push({start, end})
+    else hosts.set(editableHost, [{start, end}])
+  }
+
+  if (!hosts.size) return deleteCssHighlight({name, win})
+
+  let registry = registries.get(win)
+  if (!registry) registries.set(win, registry = new Map())
+  registry.set(name, hosts)
+
+  drawCssHighlight({name, hosts, win})
+}
+
+/**
+ * Draw the highlights of an editable again after its markup changed.
+ *
+ * Comments and formats wrap text in marker nodes, which breaks the ranges the
+ * browser is holding. The markers carry no text themselves, so the offsets
+ * still point at the right words and the highlight can be rebuilt from them.
+ *
+ * @param  {Object} options
+ * @param  {DOMNode} options.editableHost
+ * @param  {Window} [options.win]
+ */
+export function refreshCssHighlights ({
+  editableHost,
+  win = editableHost?.ownerDocument?.defaultView
+}) {
+  const registry = registries.get(win)
+  if (!registry?.size) return
+
+  for (const [name, hosts] of registry) {
+    if (!hosts.has(editableHost)) continue
+
+    for (const host of hosts.keys()) {
+      if (!host?.isConnected) hosts.delete(host)
+    }
+
+    if (!hosts.size) deleteCssHighlight({name, win})
+    else drawCssHighlight({name, hosts, win})
+  }
+}
+
+/**
+ * Turn a character range into a DOM range, for callers that need to select or
+ * measure the text rather than highlight it.
+ *
+ * @param  {Object} options
+ * @param  {DOMNode} options.editableHost
+ * @param  {Number} options.start
+ * @param  {Number} options.end
+ * @param  {Window} [options.win]
+ * @return {Range|undefined}
+ */
+export function createCssHighlightRange ({editableHost, start, end, win = window}) {
+  const {segments} = readEditable(editableHost)
+  return createRangeFromSegments({segments, start, end, win})
+}
+
+/**
+ * Remove the highlights of one name and forget where they were. Nothing does
+ * this on its own, so whoever set them has to say when they are done.
+ *
+ * @param  {Object} options
+ * @param  {String} options.name
+ * @param  {Window} [options.win]
+ */
+export function deleteCssHighlight ({name, win = window}) {
+  registries.get(win)?.delete(name)
+  win.CSS.highlights.delete(name)
+}
+
+/**
+ * Where a range sits on screen, so a caller can place something next to it.
+ * The coordinates include the scroll offset.
+ *
+ * @param  {Object} options
+ * @param  {DOMNode} options.editableHost
+ * @param  {Number} options.start
+ * @param  {Number} options.end
+ * @param  {Window} [options.win]
+ * @return {Object|undefined}
+ */
+export function getCssHighlightRects ({editableHost, start, end, win = window}) {
+  const range = createCssHighlightRange({editableHost, start, end, win})
+  if (!range) return
+
+  const bounding = range.getBoundingClientRect()
+  const rects = Array.from(range.getClientRects())
+  const {x, y} = getScrollPosition(win)
+  return {
+    bounding: translate(bounding, x, y),
+    rects: rects.map((rect) => translate(rect, x, y))
+  }
+}
+
+/**
+ * Turn a DOM position into a character offset, so a caller can tell which
+ * highlight a position falls in. Counts the same characters as
+ * getCssHighlightText(), so the two always agree on where an offset falls.
+ *
+ * @param  {Object} options
+ * @param  {DOMNode} options.editableHost
+ * @param  {DOMNode} options.container
+ * @param  {Number} options.containerOffset
+ * @return {Number|undefined}
+ */
+export function getCssHighlightTextOffset ({editableHost, container, containerOffset}) {
+  // A position in an element points before one of its children instead of
+  // into text. Resolve it to that child so the walk can spot it.
+  const beforeNode = container.nodeType === nodeType.elementNode
+    ? container.childNodes[containerOffset]
+    : undefined
+
+  const {text, leading} = readEditable(editableHost)
+  const counted = (raw) => Math.min(Math.max(raw - leading, 0), text.length)
+
+  const iterator = new NodeIterator(editableHost)
+
+  let offset = 0
+  let next
+
+  while ((next = iterator.getNext())) {
+    if (next === beforeNode) return counted(offset)
+
+    if (next.nodeType === nodeType.elementNode && next.nodeName === 'BR') {
+      offset += 1
+      continue
+    }
+    if (next.nodeType !== nodeType.textNode || next.data === '') continue
+
+    if (next === container) {
+      return counted(offset + stripInternal(next.data.slice(0, containerOffset)).length)
+    }
+    offset = offset + stripInternal(next.data).length
+  }
+
+  // The walk never met the container. For an element that means the end of the
+  // block. Anything else is a node we do not count, so there is no offset.
+  if (!beforeNode && container.nodeType === nodeType.elementNode) return counted(offset)
+}
+
+/**
+ * Render one named highlight from character offsets.
+ *
+ * @param  {Object} options
+ * @param  {String} options.name
+ * @param  {Map} options.hosts editableHost -> [{start, end}]
+ * @param  {Window} options.win
+ */
+function drawCssHighlight ({name, hosts, win}) {
+  const domRanges = []
+
+  for (const [editableHost, offsets] of hosts) {
+    const {segments} = readEditable(editableHost)
+    if (!segments.length) continue
+
+    for (const {start, end} of offsets) {
+      const range = createRangeFromSegments({segments, start, end, win})
+      if (range) domRanges.push(range)
+    }
+  }
+
+  // Keep the offsets. An editable can be empty for a moment while it renders,
+  // which does not mean the highlight has gone away.
+  if (!domRanges.length) return win.CSS.highlights.delete(name)
+
+  win.CSS.highlights.set(name, new win.Highlight(...domRanges))
+}
+
+/**
+ * Read an editable once: the text callers count their offsets against, and the
+ * segments those offsets resolve back through, out of the same walk.
+ *
+ * A <br> counts as a newline. Internal characters and the whitespace at either
+ * end of the block do not, because the clean on blur takes them out; an internal
+ * character splits its text node in two, which is what nodeOffset is for.
+ *
+ * @param  {DOMNode} element
+ * @return {Object} {text, leading, segments} with segments ordered and non
+ *   overlapping as [{node, nodeOffset, start, end}]
+ */
+function readEditable (element) {
+  const runs = []
+  let raw = ''
+
+  const push = (node, nodeOffset, data) => {
+    runs.push({node, nodeOffset, start: raw.length, end: raw.length + data.length})
+    raw += data
+  }
+
+  for (const node of new NodeIterator(element)) {
+    if (node.nodeType === nodeType.elementNode && node.nodeName === 'BR') {
+      raw += '\n'
+      continue
+    }
+    if (node.nodeType !== nodeType.textNode || node.data === '') continue
+
+    const data = node.data
+    if (!hasInternal(data)) {
+      push(node, 0, data)
+      continue
+    }
+
+    let runStart = 0
+    let runLength = 0
+    for (let index = 0; index < data.length; index++) {
+      if (!isInternal(data[index])) {
+        if (runLength === 0) runStart = index
+        runLength += 1
+        continue
+      }
+      if (runLength) push(node, runStart, data.slice(runStart, runStart + runLength))
+      runLength = 0
+    }
+    if (runLength) push(node, runStart, data.slice(runStart, runStart + runLength))
+  }
+
+  const leading = raw.length - raw.trimStart().length
+  const kept = raw.trimEnd().length
+
+  const segments = []
+  for (const run of runs) {
+    const start = Math.max(run.start, leading)
+    const end = Math.min(run.end, kept)
+    if (start >= end) continue
+
+    segments.push({
+      node: run.node,
+      nodeOffset: run.nodeOffset + (start - run.start),
+      start: start - leading,
+      end: end - leading
+    })
+  }
+
+  return {text: raw.slice(leading, Math.max(leading, kept)), leading, segments}
+}
+
+/**
+ * @param  {Object} options
+ * @param  {Array} options.segments
+ * @param  {Number} options.start
+ * @param  {Number} options.end
+ * @param  {Window} options.win
+ * @return {Range|undefined}
+ */
+function createRangeFromSegments ({segments, start, end, win}) {
+  const startPoint = findRangeBoundary(segments, start, false)
+  const endPoint = findRangeBoundary(segments, end, true)
+  if (!startPoint || !endPoint) return
+
+  const range = createRange(win)
+  range.setStart(startPoint.node, startPoint.offset)
+  range.setEnd(endPoint.node, endPoint.offset)
+  return range
+}
+
+/**
+ * Find the place in the DOM that a character offset points at. Callers count
+ * characters, the browser wants nodes.
+ *
+ * Segments only ever move forward, so the right one can be found without
+ * reading them all.
+ *
+ * @param  {Array} segments
+ * @param  {Number} target
+ * @param  {Boolean} inclusive True for a range end, false for a range start.
+ * @return {Object|undefined}
+ */
+function findRangeBoundary (segments, target, inclusive) {
+  let low = 0
+  let high = segments.length
+
+  while (low < high) {
+    const middle = (low + high) >> 1
+    const {end} = segments[middle]
+    if (inclusive ? end >= target : end > target) high = middle
+    else low = middle + 1
+  }
+
+  const segment = segments[low]
+  if (!segment) return
+
+  return {node: segment.node, offset: segment.nodeOffset + Math.max(0, target - segment.start)}
+}
+
+/**
+ * Shift a rect by a scroll offset.
+ *
+ * @param  {DOMRect} rect
+ * @param  {Number} x
+ * @param  {Number} y
+ * @return {Object}
+ */
+function translate (rect, x, y) {
+  return {
+    top: rect.top + y,
+    bottom: rect.bottom + y,
+    left: rect.left + x,
+    right: rect.right + x,
+    width: rect.width,
+    height: rect.height
+  }
+}

package/src/smartQuotes.js

@@ -20,12 +20,12 @@ export const replaceQuote = (range, index, quoteType) => {
   const startContainer = range?.startContainer
   const nodeValue = startContainer?.nodeValue
   if (!nodeValue) {
-    return null
+    return false
   }
-  const newText = `${nodeValue.substring(0, index)}${quoteType}${nodeValue.substring(index + 1)}`
-  const newTextNode = document.createTextNode(newText)
-  startContainer.replaceWith(newTextNode)
-  return newTextNode
+  const at = Math.min(index, nodeValue.length)
+  startContainer.insertData(at, quoteType)
+  startContainer.deleteData(at + quoteType.length, 1)
+  return true
 }
 
 const hasSingleOpeningQuote = (textArr, offset, singleOpeningQuote) => {
@@ -40,6 +40,35 @@ const hasSingleOpeningQuote = (textArr, offset, singleOpeningQuote) => {
   return false
 }
 
+// Returns the quote to write in place of the typed one, or undefined if the
+// typed character should be left alone.
+const getQuote = (textArr, offset, isCharSingleQuote, {quotes, singleQuotes}) => {
+  // Special case for a single quote following a double quote,
+  // which should be transformed into a single opening quote
+  if (isCharSingleQuote && shouldBeSingleOpeningQuote(textArr, offset - 2)) {
+    return singleQuotes[0]
+  }
+
+  if (shouldBeClosingQuote(textArr, offset - 2)) {
+    if (isCharSingleQuote) {
+      // Don't transform apostrophes
+      if (hasCharAfter(textArr, offset)) {
+        return
+      }
+      // Don't transform single-quote if there is no respective single-opening-quote
+      if (!hasSingleOpeningQuote(textArr, offset, singleQuotes[0])) {
+        return
+      }
+      return singleQuotes[1]
+    }
+    return quotes[1]
+  }
+
+  if (shouldBeOpeningQuote(textArr, offset - 2)) {
+    return isCharSingleQuote ? singleQuotes[0] : quotes[0]
+  }
+}
+
 export const applySmartQuotes = (range, config, char, target, cursorOffset) => {
   const isCharSingleQuote = isSingleQuote(char)
   const isCharDoubleQuote = isDoubleQuote(char)
@@ -55,37 +84,19 @@ export const applySmartQuotes = (range, config, char, target, cursorOffset) => {
 
   const offset = range.startOffset
   const textArr = [...range.startContainer.textContent]
-  let newTextNode
 
-  // Special case for a single quote following a double quote,
-  // which should be transformed into a single opening quote
-  if (isCharSingleQuote && shouldBeSingleOpeningQuote(textArr, offset - 2)) {
-    newTextNode = replaceQuote(range, offset - 1, singleQuotes[0])
-  } else if (shouldBeClosingQuote(textArr, offset - 2)) {
-    if (isCharSingleQuote) {
-      // Don't transform apostrophes
-      if (hasCharAfter(textArr, offset)) {
-        return
-      }
-      // Don't transform single-quote if there is no respective single-opening-quote
-      if (!hasSingleOpeningQuote(textArr, offset, singleQuotes[0])) {
-        return
-      }
-    }
-    const closingQuote = isCharSingleQuote ? singleQuotes[1] : quotes[1]
-    newTextNode = replaceQuote(range, offset - 1, closingQuote)
-  } else if (shouldBeOpeningQuote(textArr, offset - 2)) {
-    const openingQuote = isCharSingleQuote ? singleQuotes[0] : quotes[0]
-    newTextNode = replaceQuote(range, offset - 1, openingQuote)
+  const quote = getQuote(textArr, offset, isCharSingleQuote, config)
+  if (!quote) {
+    return
   }
 
-  if (!newTextNode) {
+  if (!replaceQuote(range, offset - 1, quote)) {
     return
   }
 
   // Resets the cursor to the currentPosition after applying the smart-quote
   const window = target.ownerDocument.defaultView
   const selection = window.getSelection()
-  selection.collapse(newTextNode, cursorOffset ?? offset)
+  selection.collapse(range.startContainer, cursorOffset ?? offset)
 }