prosemirror 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a11c83675790681267f7d5282882f967154892b408d8965e528b1c34d166876
-  data.tar.gz: 14ae8422a61cbe0be055d6ef7590a10981014430978089e14b2805ebf3100be2
+  metadata.gz: c84fca02d8a8c1f32c9162da3a22133f2ef774c035281331d7d92423d24a242f
+  data.tar.gz: ca2ec139725747838a359f43a667c1fc4b5b5249b7dba12775ffbe39985f0c38
 SHA512:
-  metadata.gz: 02ac22023a65ba9631752cf6c42b9895cfb4be99acc4d2b1922d0a9742e5d61c7d084455b0c6aec2f0c80400531870113b2ceba519f0a7a4af701de7e192c1f0
-  data.tar.gz: 8adae01f43c5ea57367db4d77605ceb28b4d606829b905440a716c64dc483c82a105898878349bb79f1fd73df4459651e9172d67546ee1d23968fd8cd3538801
+  metadata.gz: c018119a21927872e1382b1ee05f33c397781c87520b55ee4ca76f06abc2fb728ed4122043f11250cd3f8195c5ede8de4e50619bf98f93405f163fa30bd413aa
+  data.tar.gz: 3a870e5aceacd20c1ec717942f3dc4c75a97f811e8813e73c346aa71b919ab4430645593c6daec6132a1c72cd3f053e192ff812126cf22cd8f567cc5cafb8b98

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-24
+
+- `Document#transform` builds a new document from a block called with each node, children first, which keeps, replaces, removes or splices nodes. Required content that goes missing is added back and reported.
+- `Document#check` raises `InvalidDocument` for the first problem with the schema, with its path, and `Document#valid?` returns true or false.
+- `Node#blank?` is true for nodes that show nothing, like empty paragraphs.
+
 ## [0.3.0] - 2026-10-24
 
 - Import Markdown with `Prosemirror.from_markdown` (or `schema.parse_markdown`). Needs the [`commonmarker`](https://github.com/gjtorikian/commonmarker) gem, which isn't installed with this gem. GitHub Flavored Markdown tables, strikethrough and autolinks are supported, and the schema's parse rules apply, so custom types can match Markdown too. Raw HTML goes through HTML import when the herb gem is installed. YAML front matter is dropped.

data/COOKBOOK.md

@@ -18,23 +18,35 @@ class Paragraph < Prosemirror::Nodes::Paragraph
 end
 ```
 
-A paragraph that only holds spaces or line breaks is not empty. To skip those too, check the text instead, keeping paragraphs with an inline image or another leaf node:
+A paragraph that only holds spaces or line breaks is not empty. To skip those too, use `blank?`, which keeps paragraphs with an inline image or another leaf node:
 
 ```ruby
 class Paragraph < Prosemirror::Nodes::Paragraph
   def view_template(&)
-    p(&) unless blank?
+    p(&) unless node.blank?(prosemirror_schema)
   end
+end
+```
 
-  private
+`to_text` still separates empty paragraphs with a blank line, as ProseMirror does. `to_h` keeps them, so the editor gets the document back unchanged. To remove them from the document itself, see the next recipe.
 
-  def blank?
-    node.text_content.strip.empty? && node.content.all? { |child| child.text? || child.type == :hard_break }
+## Remove empty paragraphs before saving
+
+To clean a document before saving it, remove blank paragraphs with `transform`, along with the list items and lists they leave empty:
+
+```ruby
+schema = Prosemirror::Schema.tiptap(case: :camel)  # saves `bulletList`, as Tiptap expects
+document = Prosemirror.parse(params[:content], schema:).transform do |node|
+  case node
+  in { type: :paragraph | :list_item } if node.blank?(schema) then nil
+  in { type: :bullet_list | :ordered_list } if node.content.empty? then nil
+  else node
   end
 end
+record.update!(content: document.to_h)
 ```
 
-`to_text` still separates empty paragraphs with a blank line, as ProseMirror does. `to_h` keeps them, so the editor gets the document back unchanged.
+Without `case: :camel`, `to_h` writes snake_case type names like `bullet_list`, which Tiptap doesn't read. `blank?` gets the schema so that it knows your custom types: an image block isn't blank. Children are transformed first, so the list sees its remaining items. Attributes the schema doesn't declare are kept. When something the schema requires is gone, like the only paragraph of a list item kept by another rule, `transform` adds it back and reports it with `on_invalid`.
 
 ## Heading anchors
 

data/README.md

@@ -48,6 +48,32 @@ doc.select { |node| node in { type: :heading, attrs: { level: 1 } } }
 doc.content.first.text_content
 ```
 
+## Transforming documents
+
+`transform` builds a new document from a block called with each node. The block returns the node to keep, another node, an array of nodes to put in its place, or nil to remove it:
+
+```ruby
+doc = doc.transform do |node|
+  case node
+  in { type: :paragraph } if node.blank? then nil
+  in { type: :heading, attrs: { level: 1 } } then node.with(attrs: { level: 2 })
+  in { type: :bullet_list } then node.content.flat_map(&:content)  # unwrap the list
+  else node
+  end
+end
+```
+
+- Children are transformed first: the block sees a node with its transformed content, and the nodes it returns aren't transformed again.
+- Nodes are immutable: `with` returns a copy with some properties changed, like `content`, `attrs`, `marks` or `text`. Attributes the schema doesn't declare are kept.
+- `blank?` is true for nodes that show nothing: no text but whitespace, and no leaf nodes but hard breaks.
+- Adjacent text nodes with the same marks are joined. When a node's content changed and lacks what its type requires, like the only paragraph of a list item, the required nodes are added and reported with `on_invalid`.
+
+`check` raises `Prosemirror::InvalidDocument` for the first problem with the schema, with its path: an unknown type, an invalid attribute, content that doesn't match a [content expression](TYPES.md#content-expressions), or marks a node doesn't allow. `valid?` returns true or false. Rendering doesn't need a valid document.
+
+```ruby
+doc.check  # raises "doc.content[0]: invalid content for blockquote: paragraph text"
+```
+
 ## HTML import
 
 HTML import uses [Herb](https://herb-tools.dev)'s parser, which never raises on malformed HTML. Add it to your Gemfile:

data/ROADMAP.md

@@ -177,7 +177,7 @@ They differ in more than names:
 - Raw HTML in Markdown goes through the HTML importer if Herb is installed.
 - `Prosemirror.from_text`: blank lines make paragraphs, line breaks make hard breaks.
 
-### 0.4: Working with documents
+### 0.4: Working with documents (released)
 
 - Transformations that return a new document: rewrite links, unwrap lists, split paragraphs, remove empty ones.
 

data/lib/prosemirror/checker.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Prosemirror
+  # Checks a document against its schema, as ProseMirror's `Node#check`, and raises InvalidDocument for the
+  # first problem, with its path. See Document#check.
+  #
+  # Rendering and JSON parsing don't need valid content: they render what they get. This checks what
+  # they don't: node and mark types, attributes, content expressions, and the marks each node allows.
+  class Checker
+    def initialize(schema)
+      @schema = schema
+    end
+
+    def call(root)
+      name = @schema.json_type_name(root.type)
+      invalid("the top node is #{name}, not #{@schema.top_node}", name) unless root.type == @schema.top_node
+      check(root, name)
+    end
+
+    private
+
+    def check(node, path)
+      type = @schema.node_type(node.type) or invalid("unknown node type #{@schema.json_type_name(node.type)}", path)
+      return check_text(node, path) if node.text?
+
+      check_attrs(type, node.attrs, path)
+      node.content.each_with_index do |child, index|
+        @schema.node_type(child.type) or invalid("unknown node type #{@schema.json_type_name(child.type)}", "#{path}.content[#{index}]")
+      end
+      check_content(type, node, path)
+      node.content.each_with_index do |child, index|
+        child_path = "#{path}.content[#{index}]"
+        check_marks(type, child, child_path)
+        check(child, child_path)
+      end
+    end
+
+    def check_text(node, path)
+      invalid("empty text node", path) if node.text.to_s.empty?
+      invalid("text nodes have no content", path) unless node.content.empty?
+    end
+
+    def check_content(type, node, path)
+      if type.leaf?
+        invalid("#{name(type)} has no content, but has #{node.content.size} nodes", path) unless node.content.empty?
+        return
+      end
+
+      types = node.content.map { |child| @schema.node_type(child.type) }
+      return if @schema.content_match(type).match_types(types)&.valid_end?
+
+      found = node.content.map { |child| @schema.json_type_name(child.type) }.join(" ")
+      invalid("invalid content for #{name(type)}: #{found.empty? ? "nothing" : found}", path)
+    end
+
+    def check_marks(parent, node, path)
+      node.marks.each_with_index do |mark, index|
+        mark_type = @schema.mark_type(mark.type) or invalid("unknown mark type #{@schema.json_type_name(mark.type)}", "#{path}.marks[#{index}]")
+        check_attrs(mark_type, mark.attrs, "#{path}.marks[#{index}]")
+        invalid("#{name(parent)} doesn't allow #{name(mark_type)} marks", path) unless parent.allows_mark?(mark_type, @schema)
+      end
+      sorted = node.marks.reduce([]) { |set, mark| @schema.add_mark(mark, set) }
+      invalid("invalid marks: #{node.marks.map { |mark| @schema.json_type_name(mark.type) }.join(" ")}", path) unless sorted == node.marks
+    end
+
+    # Attributes are valid when building them from themselves reports nothing and changes nothing.
+    def check_attrs(type, attrs, path)
+      problems = []
+      built = type.build_attrs(attrs, report: ->(message) { problems << message })
+      invalid(problems.first, path) unless problems.empty?
+      invalid("invalid attributes: #{attrs.inspect}", path) unless built == attrs
+    end
+
+    def name(type)
+      @schema.json_type_name(type.type_name)
+    end
+
+    def invalid(message, path)
+      raise InvalidDocument.new(message, path: path)
+    end
+  end
+end

data/lib/prosemirror/document.rb

@@ -64,6 +64,38 @@ module Prosemirror
       root.text_content
     end
 
+    # A new document built from a block called with each node, children first. The block returns the node
+    # to keep, another node, an array of nodes to put in its place, or nil to remove it:
+    #
+    #   doc.transform do |node|
+    #     case node
+    #     in { type: :paragraph } if node.blank? then nil
+    #     in { type: :heading, attrs: { level: 1 } } then node.with(attrs: { level: 2 })
+    #     else node
+    #     end
+    #   end
+    #
+    # Adjacent text nodes with the same marks are joined. When a node's content changed and lacks what its
+    # content expression requires, the required nodes are added and reported with `on_invalid`.
+    def transform(&)
+      Document.new(Transformer.new(schema, &).call(root), schema: schema)
+    end
+
+    # Raises InvalidDocument for the first problem with the schema: an unknown node or mark type, invalid
+    # attributes, content that doesn't match a content expression, or marks a node doesn't allow. Returns
+    # the document.
+    def check
+      Checker.new(schema).call(root)
+      self
+    end
+
+    def valid?
+      check
+      true
+    rescue InvalidDocument
+      false
+    end
+
     def ==(other)
       other.is_a?(Document) && root == other.root
     end

data/lib/prosemirror/node.rb

@@ -11,6 +11,9 @@ module Prosemirror
   # in JSON (for example from a Tiptap extension the schema doesn't know): they are never rendered,
   # and `to_h` gives them back unchanged.
   class Node < Literal::Data
+    # Whitespace, including non-breaking spaces.
+    BLANK = /\A[[:space:]]*\z/
+
     prop :type, Symbol, &Coerce::SYMBOL
     prop :attrs, _Hash(Symbol, _Any?), default: {}.freeze, &Coerce::FROZEN
     prop :unknown_attrs, _Hash(String, _Any?), default: {}.freeze, &Coerce::FROZEN
@@ -70,6 +73,18 @@ module Prosemirror
       end
     end
 
+    # Whether the node shows nothing: no text but whitespace, and no leaf nodes but line breaks, like an
+    # empty paragraph, or a list item holding one. The schema says which nodes are leaves: an image isn't
+    # blank, and neither is a node of a type it doesn't know.
+    def blank?(schema = Prosemirror.schema)
+      [self, *descendants].none? do |node|
+        next !BLANK.match?(node.text) if node.text?
+
+        type = schema.node_type(node.type)
+        type.nil? || (type.leaf? && !type.linebreak_replacement?)
+      end
+    end
+
     def same_markup?(other)
       @type == other.type && @attrs == other.attrs && @unknown_attrs == other.unknown_attrs && @marks == other.marks
     end

data/lib/prosemirror/transformer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Prosemirror
+  # Builds a new document from a block called with each node, children first. See Document#transform.
+  #
+  # The block returns the node to keep, another node, an array of nodes to put in its place, or nil to
+  # remove it. Adjacent text nodes with the same marks are then joined, and empty ones removed. When a
+  # node's content changed and no longer has what its content expression requires, the required nodes
+  # are added, as an empty paragraph in an empty list item, and reported. Other problems are left for
+  # Document#check.
+  class Transformer
+    def initialize(schema, &block)
+      raise ArgumentError, "transform needs a block" unless block
+
+      @schema = schema
+      @block = block
+    end
+
+    # The root, with its transformed content. The root itself isn't given to the block.
+    def call(root)
+      path = @schema.json_type_name(root.type)
+      filled(root, root.with(content: transform_content(root, path)), path)
+    end
+
+    private
+
+    def transform_content(node, path)
+      content = node.content.each_with_index.flat_map { |child, index| transform(child, "#{path}.content[#{index}]") }
+      Node.join_text(content.reject { |child| child.text? && child.text.empty? })
+    end
+
+    # The nodes the block gives for a node, after its content, with their required content added: the block
+    # sees an emptied list item, and can remove it.
+    def transform(node, path)
+      changed = node.content.empty? ? node : node.with(content: transform_content(node, path))
+      nodes = case (result = @block.call(changed))
+      when nil then []
+      when Node then [result]
+      when Array then result
+      end
+      raise ArgumentError, "the transform block returns a node, an array of nodes or nil, not #{result.inspect}" unless nodes&.all?(Node)
+
+      nodes.map { |result_node| filled(node, result_node, path) }
+    end
+
+    # The node with its required content added, when its content changed.
+    def filled(original, node, path)
+      return node if node.content.equal?(original.content) || node.content == original.content
+
+      content = fill(node, node.content, path)
+      content.equal?(node.content) ? node : node.with(content: content)
+    end
+
+    # The content with the nodes its type requires added in front of it, or after it, when they can be.
+    def fill(node, content, path)
+      type = @schema.node_type(node.type)
+      types = content.map { |child| @schema.node_type(child.type) }
+      return content if type.nil? || type.leaf? || types.include?(nil)
+
+      match = @schema.content_match(type)
+      return content if match.match_types(types)&.valid_end?
+
+      if (before = match.fill_before(types, @schema, to_end: true))
+        added = created(before, node, path) and return added + content
+      elsif (after = match.match_types(types)&.fill_before([], @schema, to_end: true))
+        added = created(after, node, path) and return content + added
+      end
+      content
+    end
+
+    # Empty nodes of these types, filled with what they require, or nil when one can't be created.
+    def created(types, node, path)
+      nodes = types.map { |type| @schema.create_and_fill(type) }
+      return nil if nodes.include?(nil)
+
+      names = types.map { |type| @schema.json_type_name(type.type_name) }.join(", ")
+      @schema.report("added required #{names} to #{@schema.json_type_name(node.type)}", path: path)
+      nodes
+    end
+  end
+end

data/lib/prosemirror/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Prosemirror
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prosemirror
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Hans Lemuet
@@ -66,6 +66,7 @@ files:
 - ROADMAP.md
 - TYPES.md
 - lib/prosemirror.rb
+- lib/prosemirror/checker.rb
 - lib/prosemirror/coerce.rb
 - lib/prosemirror/content_expression.rb
 - lib/prosemirror/content_match.rb
@@ -122,6 +123,7 @@ files:
 - lib/prosemirror/rendering.rb
 - lib/prosemirror/schema.rb
 - lib/prosemirror/text_serializer.rb
+- lib/prosemirror/transformer.rb
 - lib/prosemirror/type_definition.rb
 - lib/prosemirror/utf8.rb
 - lib/prosemirror/version.rb