lib0 1.0.0-rc.2 → 1.0.0-rc.21

package/src/delta/position.js

@@ -0,0 +1,165 @@
+/**
+ * # Positions in a delta tree
+ *
+ * A {@link Pos} is a resolution-independent location in a *final* (insert-only) {@link
+ * import('./delta.js').Delta delta} tree — a cursor between two characters, a point inside a nested
+ * node, or a reference to an attribute value. It is the value an editor stores for a caret/selection
+ * and the thing a transformer maps from one bound RDT to the other (see `./transformer/`).
+ *
+ * A position is a `path` of steps plus an association (gravity):
+ * - a **string** step descends into the attribute with that key,
+ * - a **number** step is a *content* index (each character and each array element counts as 1,
+ *   matching {@link import('./delta.js').Delta}'s `childCnt`): a non-terminal number descends into
+ *   the child node at that slot, and the **trailing** number is the terminal cursor *gap*.
+ *
+ * ```
+ * [5]        cursor gap at offset 5 in the root
+ * ['a', 1]   inside attribute 'a', cursor gap at offset 1
+ * [1, 5]     descend into the child node at slot 1, cursor gap at offset 5 inside it
+ * ['a']      the value of attribute 'a' (attribute leaf; no offset)
+ * []         the root node itself
+ * ```
+ *
+ * Numbers are always read as child indices. A *number-keyed attribute* therefore has no unambiguous
+ * position: {@link marksToPositions} still emits a mark inside one, but its numeric attribute step is
+ * indistinguishable from a content index, so such a {@link Pos} mis-resolves and must not be round-
+ * tripped through {@link import('./delta.js').DeltaBuilder#addMark}. Use string attribute keys for any
+ * node that may carry marks (numeric attribute keys are not used in practice).
+ *
+ * @module delta/position
+ */
+
+import * as s from '../schema.js'
+import * as fun from '../function.js'
+import * as delta from './delta.js'
+
+/**
+ * A single step of a {@link Pos} path: a `string` attribute key, or a `number` content index.
+ *
+ * @typedef {string|number} PosStep
+ */
+
+/**
+ * A location in a delta tree. `path` descends from the node the position is relative to and ends in
+ * the terminal (a trailing-number cursor gap, or a trailing-string attribute leaf). `assoc` is the
+ * gravity at a boundary: `-1` binds to the preceding content, `1` to the following content. `attrs` is
+ * optional immutable user data carried with the position (e.g. an RDT's clientID/user metadata); it is
+ * stored on the {@link import('./delta.js').createMark mark} when the position is written with
+ * {@link import('./delta.js').DeltaBuilder#addMark} and read back by {@link marksToPositions}.
+ *
+ * @typedef {{ path: Array<PosStep>, assoc: -1|1, attrs?: object|null }} Pos
+ */
+
+/**
+ * A {@link Pos} tagged with the unique id of a stored {@link import('./delta.js').createMark mark} —
+ * what {@link marksToPositions} returns (its `attrs` is the mark's stored metadata). Add marks with
+ * {@link import('./delta.js').DeltaBuilder#addMark}.
+ *
+ * @typedef {{ id: string } & Pos} MarkPos
+ */
+
+/**
+ * Schema for a {@link Pos}.
+ *
+ * @type {s.Schema<Pos>}
+ */
+export const $pos = /* @__PURE__ */ s.$object({
+  path: s.$array(s.$union(s.$string, s.$number)),
+  assoc: s.$literal(-1, 1),
+  attrs: s.$any.optional
+})
+
+/**
+ * Create a {@link Pos} from a path, an (optional) association (gravity, default right `1`), and
+ * (optional) immutable `attrs` carried with the mark. `attrs` is omitted from the result when `null`,
+ * so a plain cursor position stays `{ path, assoc }`.
+ *
+ * @param {Array<PosStep>} path
+ * @param {-1|1} [assoc]
+ * @param {object?} [attrs]
+ * @return {Pos}
+ */
+export const create = (path, assoc = 1, attrs = null) => attrs === null ? { path, assoc } : { path, assoc, attrs }
+
+/**
+ * Structural equality of two positions: same `assoc`, `id` (a plain {@link Pos} has none ⇒ both
+ * `undefined`), `attrs` (deep), and `path`.
+ *
+ * @param {Pos|MarkPos} a
+ * @param {Pos|MarkPos} b
+ * @return {boolean}
+ */
+export const equals = (a, b) => a.assoc === b.assoc && /** @type {any} */ (a).id === /** @type {any} */ (b).id && fun.equalityDeep(a.attrs ?? null, b.attrs ?? null) && a.path.length === b.path.length && a.path.every((step, i) => step === b.path[i])
+
+/**
+ * Schema for a {@link MarkPos}.
+ *
+ * @type {s.Schema<MarkPos>}
+ */
+export const $markPos = /* @__PURE__ */ s.$object({
+  id: s.$string,
+  path: s.$array(s.$union(s.$string, s.$number)),
+  assoc: s.$literal(-1, 1),
+  attrs: s.$any.optional
+})
+
+/**
+ * Reconstruct every {@link MarkPos} stored as a {@link import('./delta.js').Mark mark} inside `d` (a
+ * settled delta). A mark's `path` is the content indices / attribute keys walked to reach it, plus the
+ * mark's own `key`. Add marks with {@link import('./delta.js').DeltaBuilder#addMark}.
+ *
+ * Subtrees are pruned via each node's conservative `maybeHasMarks` flag (`false` ⇒ guaranteed empty,
+ * skipped). This is also the **sole resetter** of that flag: a descended subtree that turns out to hold
+ * no marks has its (stale) `true` cleared to `false`, so later calls prune it. The flag is therefore a
+ * cheap hint that this read keeps eventually-accurate (a write during a read, like a lazy cache).
+ *
+ * @param {delta.DeltaAny} d
+ * @return {Array<MarkPos>}
+ */
+export const marksToPositions = d => {
+  /** @type {Array<MarkPos>} */
+  const out = []
+  /**
+   * Emit the marks in `node`'s subtree and return whether any were found (used to self-correct the flag).
+   *
+   * @param {delta.DeltaAny} node
+   * @param {Array<PosStep>} path
+   * @return {boolean}
+   */
+  const walk = (node, path) => {
+    if (!node.maybeHasMarks) return false // guaranteed no marks in this subtree
+    let found = false
+    if (node.marks !== null) {
+      for (const m of node.marks) {
+        found = true
+        out.push(m.attrs === null
+          ? { id: m.id, path: [...path, m.key], assoc: m.assoc }
+          : { id: m.id, path: [...path, m.key], assoc: m.assoc, attrs: m.attrs })
+      }
+    }
+    // a settled delta has only text/insert children; descend the delta-valued embeds
+    let i = 0
+    for (const op of node.children) {
+      if (delta.$insertOp.check(op)) {
+        for (const el of op.insert) {
+          if (delta.$deltaAny.check(el) && el.maybeHasMarks && walk(el, [...path, i])) found = true
+          i++
+        }
+      } else {
+        i += op.length
+      }
+    }
+    for (const op of node.attrs) {
+      // descend `setAttr` (a materialized value) AND `modifyAttr` (an incremental change into a not-yet-
+      // materialized sub-document attribute, which `apply` may leave on a settled node) - both hold a
+      // delta value reachable here.
+      if ((delta.$setAttrOp.check(op) || delta.$modifyAttrOp.check(op)) && delta.$deltaAny.check(op.value) && op.value.maybeHasMarks && walk(op.value, [...path, op.key])) {
+        found = true
+      }
+    }
+    node.maybeHasMarks = found // self-correct: clear a stale `true` so later reads prune this subtree
+    return found
+  }
+  walk(d, [])
+  return out
+}

package/src/delta/rdt/delta.js

@@ -0,0 +1,105 @@
+/**
+ * # In-memory delta RDT
+ *
+ * {@link deltaRDT} creates an RDT (see `../rdt.js`) whose state is the accumulated delta. Calling
+ * `applyDelta(delta, origin)` merges the incoming delta into `state` and re-emits it (with the given
+ * {@link import('../rdt.js').RDT origin}) as a `'delta'` event, so it can be bound to any other RDT. It
+ * accepts every valid delta as-is, so it never returns a fix.
+ *
+ * `state` is kept as a **final** delta (`isFinal`): it represents the current document, so a `delete`
+ * or `deleteAttr` removes the content/attribute outright instead of accumulating a delete-op marker.
+ * The `delta` getter therefore always returns a clean insert-only document.
+ *
+ * @module delta/rdt/delta
+ */
+
+import { ObservableV2 } from '../../observable.js'
+import * as delta from '../delta.js'
+import * as mux from '../../mutex.js'
+
+/**
+ * @template T
+ * @typedef {import('../../schema.js').Schema<T>} Schema
+ */
+
+/**
+ * @template {delta.DeltaConf} Conf
+ * @typedef {import('../rdt.js').RDT<Conf>} RDT
+ */
+
+/**
+ * An in-memory RDT whose state is the accumulated delta. Calling `applyDelta` merges the incoming delta
+ * into `state` (via {@link delta.DeltaBuilder#apply}) and re-emits it as a `'delta'`.
+ *
+ * @template {delta.DeltaConf} Conf
+ * @implements {RDT<Conf>}
+ * @extends {ObservableV2<{ delta: (delta: delta.Delta<Conf>, origin: any) => void, destroy: (rdt: DeltaRDT<Conf>) => void }>}
+ */
+class DeltaRDT extends ObservableV2 {
+  /**
+   * @param {Schema<delta.Delta<Conf>>} $delta schema of the deltas this RDT produces
+   */
+  constructor ($delta) {
+    super()
+    this.$delta = $delta
+    /**
+     * @type {delta.DeltaBuilderAny?}
+     */
+    this.state = null
+    this._mux = mux.createMutex()
+  }
+
+  /**
+   * Merge an incoming delta into the current state and notify observers. Always returns `null`: this
+   * RDT accepts every valid delta unchanged, so it never produces a fix.
+   *
+   * @param {delta.Delta<Conf>} d
+   * @param {any} [origin] who produced the change; forwarded verbatim on the emitted `'delta'` event so
+   * listeners can recognise (and skip) changes they made themselves — see {@link RDT} “Origins”. Defaults
+   * to `null` (an anonymous/local change).
+   * @return {null}
+   */
+  applyDelta (d, origin = null) {
+    if (d.isEmpty()) return null
+    this._mux(() => {
+      if (this.state == null) {
+        // start from an empty *final* document (see module doc) so deletes/deleteAttrs — even in the
+        // very first delta — remove content instead of leaving delete-op markers
+        this.state = delta.create(d.name)
+        this.state.isFinal = true
+      }
+      this.state.apply(d) // `final` defaults to `state.isFinal`, so deletes clean up the state
+    })
+    // emit AFTER releasing the mutex. When bound to a fix-producing RDT, that side's fix is mapped
+    // back here and applied via a synchronous re-entrant `applyDelta` while this call is still on the
+    // stack; with the emit inside the mutex that re-entrant mutation would be dropped. The binding's
+    // own mutex still breaks the echo loop. `d` is emitted as a shared read delta (the RDT only read it
+    // into `state`); a consumer that needs to mutate it deep-clones it first (see the `RDT` typedef).
+    this.emit('delta', [d, origin])
+    return null
+  }
+
+  /**
+   * The current state as a delta: the accumulated `state`, or an empty delta when nothing has been
+   * applied yet.
+   *
+   * @return {delta.Delta<Conf>}
+   */
+  get delta () {
+    // `state` is a loosely-typed `DeltaBuilderAny`; narrow it to this RDT's read `Delta<Conf>` view.
+    return /** @type {delta.Delta<Conf>} */ (/** @type {unknown} */ (this.state ?? delta.create(this.$delta)))
+  }
+
+  destroy () {
+    this.emit('destroy', [this])
+    super.destroy()
+  }
+}
+
+/**
+ * Create a {@link DeltaRDT} for deltas described by `$delta`.
+ *
+ * @template {delta.DeltaConf} Conf
+ * @param {Schema<delta.Delta<Conf>>} $delta
+ */
+export const deltaRDT = $delta => new DeltaRDT($delta)

package/src/delta/rdt/dom.js

@@ -0,0 +1,307 @@
+/* global MutationObserver */
+
+/**
+ * # DOM delta RDT
+ *
+ * {@link domRDT} creates an RDT (see `../rdt.js`) backed by a live DOM subtree. DOM mutations are
+ * observed with a `MutationObserver`, turned into deltas (by diffing the new DOM state against the
+ * last-known one) and emitted as `'delta'` events (with the RDT itself as their
+ * {@link import('../rdt.js').RDT origin}); incoming deltas are applied back onto the DOM. This lets a
+ * DOM subtree be bound to any other RDT.
+ *
+ * @module delta/rdt/dom
+ */
+
+import { ObservableV2 } from '../../observable.js'
+import * as delta from '../delta.js'
+import * as dom from '../../dom.js'
+import * as error from '../../error.js'
+import * as math from '../../math.js'
+import * as s from '../../schema.js'
+
+/**
+ * @template T
+ * @typedef {import('../../schema.js').Schema<T>} Schema
+ */
+
+/**
+ * @template {delta.DeltaConf} Conf
+ * @typedef {import('../rdt.js').RDT<Conf>} RDT
+ */
+
+/**
+ * Recursively convert a DOM node into a {@link DomDelta} (an "insert everything" delta describing the
+ * node, its attributes, and its subtree).
+ *
+ * @param {Node} domNode
+ * @return {DomDelta}
+ */
+const domToDelta = domNode => {
+  if (dom.$element.check(domNode)) {
+    const d = delta.create(domNode.nodeName.toLowerCase())
+    for (let i = 0; i < domNode.attributes.length; i++) {
+      const attr = /** @type {Attr} */ (domNode.attributes.item(i))
+      d.setAttr(attr.nodeName, attr.value)
+    }
+    domNode.childNodes.forEach(child => {
+      d.insert(dom.$text.check(child) ? (child.textContent ?? '') : [domToDelta(child)])
+    })
+    return /** @type {DomDelta} */ (d)
+  }
+  /* c8 ignore next */ // defensive: only element nodes are ever rendered/observed
+  error.unexpectedCase()
+}
+
+/**
+ * Render a {@link DomDelta} into a fresh DOM element (the inverse of {@link domToDelta}).
+ *
+ * @param {DomDelta} d
+ * @return {Element}
+ */
+const deltaToDom = d => {
+  if (delta.$deltaAny.check(d)) {
+    const n = dom.element(/** @type {string} */ (d.name))
+    for (const change of d.attrs) {
+      if (delta.$setAttrOp.check(change)) {
+        n.setAttribute(change.key, change.value)
+      }
+    }
+    d.children.forEach(child => {
+      if (delta.$insertOp.check(child)) {
+        n.append(...child.insert.map(el => deltaToDom(/** @type {DomDelta} */ (el))))
+      } else if (delta.$textOp.check(child)) {
+        n.append(dom.text(child.insert))
+      }
+    })
+    return n
+  }
+  /* c8 ignore next */ // defensive: deltaToDom is only ever called on delta nodes
+  error.unexpectedCase()
+}
+
+/**
+ * Apply a {@link DomDelta} as an incremental change onto an existing DOM element, mutating it in place.
+ *
+ * The element's children are addressed in *content* coordinates: each element child is one position,
+ * each character of a text node is one position. `childIndex` walks `el.childNodes`; `childOffset` is
+ * the offset within the current text node. `child` is re-read on every loop step because the previous
+ * step may have inserted, removed or split nodes.
+ *
+ * @param {Element} el
+ * @param {DomDelta} d
+ */
+const applyDeltaToDom = (el, d) => {
+  for (const change of d.attrs) {
+    if (delta.$deleteAttrOp.check(change)) {
+      el.removeAttribute(change.key)
+    } else if (delta.$setAttrOp.check(change)) {
+      el.setAttribute(change.key, change.value)
+    }
+  }
+  let childIndex = 0
+  let childOffset = 0
+  d.children.forEach(change => {
+    if (delta.$retainOp.check(change)) {
+      let len = change.retain
+      while (len > 0) {
+        const child = el.childNodes[childIndex]
+        /* c8 ignore next */ // defensive: a well-formed delta never advances past the children
+        if (child == null) break
+        if (dom.$text.check(child)) {
+          const remaining = child.length - childOffset
+          if (remaining <= len) {
+            len -= remaining
+            childOffset = 0
+            childIndex++
+          } else {
+            childOffset += len
+            len = 0
+          }
+        } else {
+          childIndex++
+          len--
+        }
+      }
+    } else if (delta.$deleteOp.check(change)) {
+      let len = change.length
+      while (len > 0) {
+        const child = el.childNodes[childIndex]
+        /* c8 ignore next */ // defensive: a well-formed delta never deletes past the children
+        if (child == null) break
+        if (dom.$text.check(child)) {
+          const childLen = child.length
+          if (childOffset === 0 && childLen <= len) {
+            child.remove()
+            len -= childLen
+          } else {
+            const spliceLen = math.min(len, childLen - childOffset)
+            child.deleteData(childOffset, spliceLen)
+            len -= spliceLen
+            if (child.length <= childOffset) {
+              childOffset = 0
+              childIndex++
+            }
+          }
+        } else {
+          child.remove()
+          len--
+        }
+      }
+    } else if (delta.$insertOp.check(change) || delta.$textOp.check(change)) {
+      if (childOffset > 0) {
+        dom.$text.cast(el.childNodes[childIndex]).splitText(childOffset)
+        childIndex++
+        childOffset = 0
+      }
+      const ref = el.childNodes[childIndex] ?? null
+      if (delta.$textOp.check(change)) {
+        el.insertBefore(dom.text(change.insert), ref)
+        childIndex++
+      } else {
+        el.insertBefore(dom.fragment(change.insert.map(c => deltaToDom(/** @type {DomDelta} */ (c)))), ref)
+        childIndex += change.insert.length
+      }
+    } else if (delta.$modifyOp.check(change)) {
+      applyDeltaToDom(dom.$element.cast(el.childNodes[childIndex]), /** @type {DomDelta} */ (change.value))
+      childIndex++
+    /* c8 ignore next 3 */ // unreachable: $domDelta children are only retain/delete/insert/text/modify
+    } else {
+      error.unexpectedCase()
+    }
+  })
+}
+
+/**
+ * Schema describing the deltas produced/consumed by a {@link DomRDT}: a recursive node with a string
+ * name, string→string attributes, and text content.
+ */
+export const $domDelta = /* @__PURE__ */ delta.$delta({ name: s.$string, attrs: s.$record(s.$string, s.$string), children: s.$never, text: true, recursiveChildren: true })
+
+/**
+ * The {@link delta.DeltaConf} of the deltas a {@link DomRDT} produces/consumes (see {@link $domDelta}).
+ *
+ * @typedef {{ name: string, attrs: { [key:string]: string }, text: true, recursiveChildren: true }} DomConf
+ */
+
+/**
+ * @typedef {delta.Delta<DomConf>} DomDelta
+ */
+
+/**
+ * An RDT backed by a live DOM subtree. DOM mutations observed via `MutationObserver` are diffed
+ * against the last-known state and emitted as deltas; incoming deltas are applied back onto the DOM.
+ *
+ * @implements {RDT<DomConf>}
+ * @extends {ObservableV2<{ delta: (delta: delta.Delta<DomConf>, origin: any) => void, destroy: (rdt: DomRDT) => void }>}
+ */
+class DomRDT extends ObservableV2 {
+  /**
+   * @param {Element} observedNode
+   */
+  constructor (observedNode) {
+    super()
+    /**
+     * @type {Schema<DomDelta>}
+     */
+    this.$delta = /** @type {any} */ ($domDelta)
+    this.observedNode = observedNode
+    /**
+     * Last-known DOM state. The observe path diffs the live DOM against this to compute the change to
+     * emit, then advances it; `applyDelta` re-syncs it after mutating the DOM.
+     *
+     * @type {DomDelta}
+     */
+    this._state = domToDelta(observedNode)
+    this.observer = new MutationObserver(this._mutationHandler)
+    this.observer.observe(observedNode, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      characterDataOldValue: true
+    })
+  }
+
+  /**
+   * Pull the local DOM changes accumulated since the last sync as a delta (by diffing the live DOM
+   * against `_state`), advancing `_state` to the current DOM.
+   *
+   * @return {DomDelta}
+   */
+  _pull () {
+    const next = domToDelta(this.observedNode)
+    const change = delta.diff(this._state, next)
+    this._state = next
+    return change
+  }
+
+  /**
+   * @param {MutationRecord[]} mutations
+   */
+  _mutationHandler = mutations => {
+    if (mutations.length === 0) return
+    const change = this._pull()
+    // a locally-observed DOM edit: this RDT is the producer, so it is the origin (see {@link RDT})
+    if (!change.isEmpty()) this.emit('delta', [change, this])
+  }
+
+  /**
+   * Apply a foreign delta onto the DOM.
+   *
+   * The DOM may have been edited locally (`b`) since the last sync, concurrently with the incoming
+   * change (`d`). We pull `b` first and rebase the two against each other (OT) so neither is lost:
+   * `d` rebased onto `b` is applied to the DOM, and `b` rebased onto `d` is returned as the fix so the
+   * binding pipes it back through the transformer to the other side.
+   *
+   * @param {delta.Delta<DomConf>} d
+   * @param {any} [origin] who produced `d`; forwarded verbatim on the emitted `'delta'` event so
+   * listeners can recognise (and skip) their own changes — see {@link RDT} “Origins”. Defaults to `null`
+   * (an anonymous/local change).
+   * @return {delta.DeltaBuilder<DomConf> | null} the rebased local change (`b`), or `null` when there
+   * were no concurrent edits
+   */
+  applyDelta (d, origin = null) {
+    const b = this._pull()
+    /** @type {DomDelta} */
+    let toApply = d
+    /** @type {DomDelta?} */
+    let fix = null
+    if (!b.isEmpty()) {
+      // clone both sides so neither original is mutated by the in-place `rebase`
+      toApply = delta.clone(d).rebase(b, true) // d on top of the local DOM (which has b)
+      const bOnD = delta.clone(b).rebase(d, false) // b on top of d, for the other side
+      fix = bOnD.isEmpty() ? null : bOnD
+    }
+    applyDeltaToDom(this.observedNode, toApply)
+    this._state = domToDelta(this.observedNode)
+    // MutationObserver callbacks are async, so the Binding's (synchronous) mutex cannot suppress the
+    // echo of our own write — draining the self-caused records here is what prevents it.
+    this.observer.takeRecords()
+    // Forward the effective change so a chained binding on the other side picks it up; the binding
+    // that fed us `d` swallows this re-emit via its own mutex (see ../rdt.js). `fix` is a freshly
+    // rebased builder at runtime, returned as the owned change the binding maps on.
+    this.emit('delta', [toApply, origin])
+    return /** @type {delta.DeltaBuilder<DomConf>?} */ (fix)
+  }
+
+  /**
+   * The current state as a delta: an "insert everything" delta describing the observed subtree.
+   *
+   * @return {delta.Delta<DomConf>}
+   */
+  get delta () {
+    return domToDelta(this.observedNode)
+  }
+
+  destroy () {
+    this.emit('destroy', [this])
+    super.destroy()
+    this.observer.disconnect()
+  }
+}
+
+/**
+ * Create a {@link DomRDT} that observes and edits `dom`.
+ *
+ * @param {Element} dom
+ */
+export const domRDT = dom => new DomRDT(dom)