Repository Public
1// SP Notes Core2// File: Sources/SPNotesDocument/Model.swift3// Description: Public document model: JSON values, the raw ProseMirror tree (PMNode / PMMark) and the flattened4// editing model (NoteDocument, Line, Container, InlineRun) with its lossless conversion both ways.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910// MARK: - JSON1112/// An arbitrary JSON value. Integers stay integers (`2` decodes to `.int(2)`, `2.5` and `2.0` to `.double`).13/// Plain `==` is structural; use `semanticallyEquals(_:)` when `.int(2)` must equal `.double(2.0)`.14public enum JSONValue: Sendable, Hashable, Codable {15 case null16 case bool(Bool)17 case int(Int64)18 case double(Double)19 case string(String)20 case array([JSONValue])21 case object([String: JSONValue])2223 public init(from decoder: Decoder) throws {24 let c = try decoder.singleValueContainer()25 if c.decodeNil() { self = .null }26 else if let v = try? c.decode(Bool.self) { self = .bool(v) }27 else if let v = try? c.decode(Int64.self) { self = .int(v) }28 else if let v = try? c.decode(Double.self) { self = .double(v) }29 else if let v = try? c.decode(String.self) { self = .string(v) }30 else if let v = try? c.decode([JSONValue].self) { self = .array(v) }31 else if let v = try? c.decode([String: JSONValue].self) { self = .object(v) }32 else { throw DecodingError.dataCorruptedError(in: c, debugDescription: "Unsupported JSON value") }33 }3435 public func encode(to encoder: Encoder) throws {36 var c = encoder.singleValueContainer()37 switch self {38 case .null: try c.encodeNil()39 case .bool(let v): try c.encode(v)40 case .int(let v): try c.encode(v)41 case .double(let v): try c.encode(v)42 case .string(let v): try c.encode(v)43 case .array(let v): try c.encode(v)44 case .object(let v): try c.encode(v)45 }46 }47}4849/// Errors thrown when reading a document.50public enum DocumentError: Error, Sendable, Hashable {51 /// The bytes are not valid JSON (message, byte offset).52 case invalidJSON(String, offset: Int)53 /// The JSON is valid but is not a ProseMirror node (no string `type`, a child that is not an object…).54 case invalidNode(String)55}5657// MARK: - Raw ProseMirror tree5859/// A ProseMirror mark (`bold`, `link`…). Marks carrying keys other than `type` / `attrs` are kept losslessly by60/// their owning node (see `PMNode.extra`).61public struct PMMark: Sendable, Hashable, Codable {62 public var type: String63 public var attrs: [String: JSONValue]?6465 public init(type: String, attrs: [String: JSONValue]? = nil) {66 self.type = type67 self.attrs = attrs68 }6970 init?(json: JSONValue) {71 guard case .object(let o) = json, case .string(let t)? = o["type"] else { return nil }72 var attrs: [String: JSONValue]?73 if let a = o["attrs"] { guard case .object(let ao) = a else { return nil }; attrs = ao }74 guard o.keys.allSatisfy({ $0 == "type" || $0 == "attrs" }) else { return nil }75 self.type = t76 self.attrs = attrs77 }7879 /// The JSON form of the mark.80 public var jsonValue: JSONValue {81 var o: [String: JSONValue] = ["type": .string(type)]82 if let attrs { o["attrs"] = .object(attrs) }83 return .object(o)84 }8586 public init(from decoder: Decoder) throws {87 let v = try JSONValue(from: decoder)88 guard let m = PMMark(json: v) else {89 throw DecodingError.dataCorrupted(.init(codingPath: decoder.codingPath, debugDescription: "Invalid mark"))90 }91 self = m92 }9394 public func encode(to encoder: Encoder) throws { try jsonValue.encode(to: encoder) }95}9697/// A raw ProseMirror node, exactly as stored by the backend. Decoding then encoding gives semantically identical98/// JSON: absent vs empty `attrs` / `content` are distinguished, and unknown keys are preserved in `extra`.99public struct PMNode: Sendable, Hashable, Codable {100 public var type: String101 public var attrs: [String: JSONValue]?102 public var content: [PMNode]?103 public var text: String?104 public var marks: [PMMark]?105 /// Unknown keys, preserved. Also holds a known key whose value has an unexpected shape (e.g. `attrs: null`).106 public var extra: [String: JSONValue]107108 public init(type: String, attrs: [String: JSONValue]? = nil, content: [PMNode]? = nil, text: String? = nil,109 marks: [PMMark]? = nil, extra: [String: JSONValue] = [:]) {110 self.type = type111 self.attrs = attrs112 self.content = content113 self.text = text114 self.marks = marks115 self.extra = extra116 }117118 /// Builds a node from a decoded JSON object. Throws `DocumentError.invalidNode` when the value is not a node.119 public init(json: JSONValue) throws {120 guard case .object(var o) = json else { throw DocumentError.invalidNode("A node must be a JSON object") }121 guard case .string(let t)? = o["type"] else { throw DocumentError.invalidNode("A node must have a string type") }122 o["type"] = nil123 type = t124 if case .object(let a)? = o["attrs"] { attrs = a; o["attrs"] = nil } else { attrs = nil }125 if case .array(let items)? = o["content"] {126 content = try items.map { try PMNode(json: $0) }127 o["content"] = nil128 } else { content = nil }129 if case .string(let s)? = o["text"] { text = s; o["text"] = nil } else { text = nil }130 if case .array(let items)? = o["marks"] {131 let parsed = items.compactMap { PMMark(json: $0) }132 if parsed.count == items.count { marks = parsed; o["marks"] = nil } else { marks = nil }133 } else { marks = nil }134 extra = o135 }136137 /// The JSON form of the node.138 public var jsonValue: JSONValue {139 var o = extra140 o["type"] = .string(type)141 if let attrs { o["attrs"] = .object(attrs) }142 if let content { o["content"] = .array(content.map(\.jsonValue)) }143 if let text { o["text"] = .string(text) }144 if let marks { o["marks"] = .array(marks.map(\.jsonValue)) }145 return .object(o)146 }147148 /// Parses a node from JSON bytes.149 public init(data: Data) throws { try self.init(json: try JSONValue(data: data)) }150151 /// Canonical JSON bytes (sorted keys, no insignificant whitespace).152 public func jsonData() -> Data { jsonValue.canonicalData() }153154 public init(from decoder: Decoder) throws {155 do { try self.init(json: try JSONValue(from: decoder)) } catch let e as DocumentError {156 throw DecodingError.dataCorrupted(.init(codingPath: decoder.codingPath, debugDescription: "\(e)"))157 }158 }159160 public func encode(to encoder: Encoder) throws { try jsonValue.encode(to: encoder) }161}162163// MARK: - Flattened editing model164165/// What a node carried besides the fields of the editing model; lets an untouched node re-serialize identically.166struct Preserved: Sendable, Hashable {167 /// `attrs` was present and empty (`{}`), as opposed to absent.168 var emptyAttrs = false169 /// `content` was present and empty (`[]`), as opposed to absent.170 var emptyContent = false171 var marks: [PMMark]?172 var extra: [String: JSONValue] = [:]173}174175/// One ancestor of a line: a list, a list item, a quote, a callout… Every line under the same container node176/// carries an equal `Container` (same `key`); consecutive lines sharing a key at a depth form one node.177public struct Container: Sendable, Hashable {178 /// Local instance id, unique per container node instance in the document. Not persisted.179 public var key: Int180 public var type: String181 public var attrs: [String: JSONValue]182 var preserved = Preserved()183184 public init(key: Int, type: String, attrs: [String: JSONValue] = [:]) {185 self.key = key186 self.type = type187 self.attrs = attrs188 }189}190191/// A piece of inline content. Offsets count UTF-16 code units of text; an atom counts as exactly 1 unit.192public enum InlineRun: Sendable, Hashable {193 /// Text with its marks, in document order of the marks.194 case text(String, marks: [PMMark])195 /// An inline leaf kept raw: `hardBreak`, `mention`, `inlineMath`, `footnoteRef`, unknown inline nodes.196 case atom(PMNode)197}198199/// The content of a line.200public enum LineContent: Sendable, Hashable {201 /// A text block (paragraph, heading, code block, footnote, details summary, unknown text block).202 case inline([InlineRun])203 /// A block kept raw (table with its whole subtree, image, file, block math, rule, video, unknown leaf, empty container).204 /// The line's `type` and `attrs` are authoritative; the node supplies everything else (see `Line.atomNode`).205 case blockAtom(PMNode)206}207208/// One editable line: a text block or a block atom, with the chain of containers it lives in.209public struct Line: Sendable, Hashable {210 /// Ancestors from outermost to innermost, the `doc` node excluded.211 public var path: [Container]212 public var type: String213 public var attrs: [String: JSONValue]214 public var content: LineContent215 var preserved = Preserved()216217 public init(path: [Container] = [], type: String, attrs: [String: JSONValue] = [:], content: LineContent) {218 self.path = path219 self.type = type220 self.attrs = attrs221 self.content = content222 }223}224225/// Outcome of a three-way merge.226public enum MergeResult: Sendable, Hashable {227 case merged(NoteDocument)228 case conflict229}230231/// A note as a flat list of lines. Converting ProseMirror JSON to lines and back is lossless for an unmodified document.232public struct NoteDocument: Sendable, Hashable {233 public var lines: [Line]234 /// The `doc` node without its children (type, attrs, unknown keys); `content` is `[]` or nil, as received.235 var root: PMNode236 var nextKey: Int237238 /// A new note: one empty paragraph with a fresh block id.239 public init() {240 root = PMNode(type: NodeType.doc)241 nextKey = 1242 lines = [Line.paragraph()]243 }244245 /// A document made of the given lines. Container keys are taken as they are.246 public init(lines: [Line]) {247 root = PMNode(type: NodeType.doc)248 self.lines = lines249 nextKey = (lines.flatMap(\.path).map(\.key).max() ?? 0) + 1250 }251252 /// Flattens a ProseMirror `doc` node.253 public init(node: PMNode) {254 var shell = node255 shell.content = node.content == nil ? nil : []256 root = shell257 nextKey = 1258 lines = []259 for child in node.content ?? [] { flatten(child, path: []) }260 }261262 /// Parses ProseMirror JSON bytes (a `doc` node).263 public init(json: Data) throws { self.init(node: try PMNode(data: json)) }264265 /// Imports Markdown with the rules of the server import; the result is valid for the web schema and has block ids.266 public init(markdown: String) { self = MarkdownImport.document(markdown, resolvePage: nil) }267268 /// Rebuilds the ProseMirror tree: consecutive lines sharing a container key at a depth form one node.269 public func pmNode() -> PMNode {270 var node = root271 let children = Self.build(lines[...], depth: 0)272 node.content = children.isEmpty ? (root.content == nil ? nil : []) : children273 return node274 }275276 /// Canonical JSON bytes of the document (sorted keys).277 public func jsonData() throws -> Data { pmNode().jsonData() }278279 /// A key no container of this document uses; for editors creating containers.280 public mutating func newContainerKey() -> Int {281 defer { nextKey += 1 }282 return nextKey283 }284285 /// Gives a 10-character id to every block that needs one and lacks it or duplicates an earlier one286 /// (same rule and traversal order as the server's `ensureBlockIds`).287 public mutating func ensureBlockIds() { _ = assignBlockIds() }288289 /// Plain text, equal to the server's `docText`.290 public func plainText() -> String { TextTools.docText(pmNode()) }291292 /// Word count of `plainText()`, equal to the server's.293 public var wordCount: Int { TextTools.wordCount(plainText()) }294295 /// First non-empty line of text, whitespace collapsed, cut to `maxLength` characters (ending with `…` when cut).296 public func preview(maxLength: Int) -> String { TextTools.preview(plainText(), maxLength: maxLength) }297298 /// Markdown, equal to the server's `toMarkdown`.299 public func markdown() -> String { MarkdownExport.markdown(pmNode()) }300301 /// A standalone HTML5 file of the note.302 public func html(title: String) -> String { HTMLExport.page(pmNode(), title: title) }303304 /// Three-way merge by top-level block identity; conservative (see `Merge.swift`).305 public static func merge(base: NoteDocument, mine: NoteDocument, theirs: NoteDocument) -> MergeResult {306 Merger.merge(base: base, mine: mine, theirs: theirs)307 }308309 /// Whether both documents serialize to the same JSON (container key numbering is ignored).310 public func isStructurallyEqual(to other: NoteDocument) -> Bool {311 pmNode().jsonValue.semanticallyEquals(other.pmNode().jsonValue)312 }313}314315// MARK: - Flatten / rebuild316317enum BlockShape { case textBlock, atom, container }318319extension NoteDocument {320 static func shape(of n: PMNode) -> BlockShape {321 if n.text != nil { return .atom }322 if Schema.textBlocks.contains(n.type) { return .textBlock }323 if Schema.blockAtoms.contains(n.type) { return .atom }324 guard let kids = n.content, !kids.isEmpty else { return .atom }325 if Schema.containers.contains(n.type) { return .container }326 return kids.contains { $0.text != nil || Schema.inlineTypes.contains($0.type) } ? .textBlock : .container327 }328329 private mutating func flatten(_ n: PMNode, path: [Container]) {330 switch Self.shape(of: n) {331 case .textBlock:332 lines.append(Line(textBlock: n, path: path))333 case .atom:334 lines.append(Line(blockAtom: n, path: path))335 case .container:336 var c = Container(key: newContainerKey(), type: n.type, attrs: n.attrs ?? [:])337 c.preserved = Preserved(emptyAttrs: n.attrs?.isEmpty == true, marks: n.marks, extra: n.extra)338 for child in n.content ?? [] { flatten(child, path: path + [c]) }339 }340 }341342 private static func build(_ slice: ArraySlice<Line>, depth: Int) -> [PMNode] {343 var out: [PMNode] = []344 var i = slice.startIndex345 while i < slice.endIndex {346 let line = slice[i]347 guard line.path.count > depth else { out.append(line.node); i += 1; continue }348 let frame = line.path[depth]349 var j = i + 1350 while j < slice.endIndex, slice[j].path.count > depth, slice[j].path[depth].key == frame.key { j += 1 }351 let p = frame.preserved352 out.append(PMNode(type: frame.type, attrs: frame.attrs.isEmpty ? (p.emptyAttrs ? [:] : nil) : frame.attrs,353 content: build(slice[i..<j], depth: depth + 1), marks: p.marks, extra: p.extra))354 i = j355 }356 return out357 }358}359360extension Line {361 /// A text-block line from its raw node.362 init(textBlock n: PMNode, path: [Container]) {363 var runs: [InlineRun] = []364 var lastTextMarks: [PMMark]?365 for child in n.content ?? [] {366 if child.type == NodeType.text, let t = child.text, !t.isEmpty, child.attrs == nil, child.content == nil,367 child.extra.isEmpty, child.marks?.isEmpty != true, lastTextMarks != (child.marks ?? []) {368 runs.append(.text(t, marks: child.marks ?? []))369 lastTextMarks = child.marks ?? []370 } else {371 // Atoms, and text nodes this model could not give back identically, are kept raw.372 runs.append(.atom(child))373 lastTextMarks = nil374 }375 }376 self.init(path: path, type: n.type, attrs: n.attrs ?? [:], content: .inline(runs))377 preserved = Preserved(emptyAttrs: n.attrs?.isEmpty == true, emptyContent: n.content?.isEmpty == true,378 marks: n.marks, extra: n.extra)379 }380381 /// A block-atom line from its raw node; `type` and `attrs` mirror the node.382 public init(blockAtom n: PMNode, path: [Container] = []) {383 self.init(path: path, type: n.type, attrs: n.attrs ?? [:], content: .blockAtom(n))384 }385386 /// The ProseMirror node of this line alone (without its containers).387 public var node: PMNode {388 switch content {389 case .blockAtom(var n):390 n.type = type391 n.attrs = attrs.isEmpty ? (n.attrs?.isEmpty == true ? [:] : nil) : attrs392 return n393 case .inline(let runs):394 let kids = InlineTools.nodes(from: runs)395 return PMNode(type: type, attrs: attrs.isEmpty ? (preserved.emptyAttrs ? [:] : nil) : attrs,396 content: kids.isEmpty ? (preserved.emptyContent ? [] : nil) : kids,397 marks: preserved.marks, extra: preserved.extra)398 }399 }400401 /// For a block atom: the raw node with the line's `type` and `attrs` applied; nil for a text line.402 public var atomNode: PMNode? {403 if case .blockAtom = content { return node }404 return nil405 }406}407