prosereflect 0.2.0 → 0.3.0

data/docs/_features/node-types.adoc

@@ -0,0 +1,124 @@
+---
+layout: default
+title: Node Types
+parent: Features
+nav_order: 1
+---
+= Node Types
+
+prosereflect provides node classes for all standard ProseMirror node types. Each inherits from `Prosereflect::Node` and defines a `PM_TYPE` constant.
+
+== Block Nodes
+
+=== Document
+
+Top-level container. Create with `Document.create`:
+
+[source,ruby]
+----
+doc = Prosereflect::Document.create
+doc.add_paragraph("Hello world")
+----
+
+Convenience methods: `tables`, `paragraphs`, `find_first`, `find_all`, `find_children`, `add_paragraph`, `add_heading`, `add_table`, `add_image`, `add_bullet_list`, `add_ordered_list`, `add_blockquote`, `add_horizontal_rule`, `add_code_block_wrapper`, `add_user`.
+
+=== Paragraph
+
+Represents a paragraph of text.
+
+[source,ruby]
+----
+para = Prosereflect::Paragraph.new
+para.add_text("Hello")
+para.text_content  # => "Hello"
+----
+
+=== Heading
+
+Heading with level attribute (1-6):
+
+[source,ruby]
+----
+heading = Prosereflect::Heading.new
+heading.level = 2
+heading.add_text("Title")
+----
+
+=== Table, TableRow, TableCell, TableHeader
+
+Table structures with convenience methods:
+
+[source,ruby]
+----
+table = doc.add_table
+row = table.add_row
+cell = row.add_cell
+cell.add_paragraph("Data")
+----
+
+Table methods: `header_row`, `data_rows`, `cell_at(row, col)`, `rows`.
+
+=== Lists
+
+`BulletList` and `OrderedList` contain `ListItem` children:
+
+[source,ruby]
+----
+list = doc.add_bullet_list
+item = list.add_item
+item.add_paragraph("First item")
+----
+
+`OrderedList` supports a `start` attribute for numbering.
+
+=== Blockquote
+
+Contains block-level children:
+
+[source,ruby]
+----
+quote = doc.add_blockquote
+quote.add_paragraph("To be or not to be")
+----
+
+=== CodeBlockWrapper and CodeBlock
+
+Code blocks with syntax highlighting:
+
+[source,ruby]
+----
+wrapper = doc.add_code_block_wrapper
+block = wrapper.add_code_block("puts 'hello'", language: "ruby")
+----
+
+=== Image
+
+Inline image node with `src`, `alt`, `title`, `width`, `height` attributes.
+
+=== HorizontalRule
+
+Horizontal rule element with `style`, `width`, `thickness` attributes.
+
+=== HardBreak
+
+Inline break element within paragraphs.
+
+== Text Nodes
+
+`Prosereflect::Text` represents a text node with `text` attribute and optional marks. `node_size` returns `text.length + 1`.
+
+== Common Methods
+
+All node types inherit from `Node`:
+
+* `node_size` -- size in the document position space
+* `text?` -- whether this is a text node
+* `cut(from, to)` -- return a copy with content restricted to range
+* `copy(content)` -- return a copy with different content
+* `find_first(type)`, `find_all(type)`, `find_children(klass)` -- node traversal
+* `add_child(node)` -- append a child
+* `text_content` -- combined text of all descendant text nodes
+* `to_h` -- serialize to ProseMirror JSON hash
+* `resolve(pos)` -- resolve a position to a `ResolvedPos`
+* `nodes_between(from, to)` -- iterate nodes in a range
+* `descendants` -- iterate all descendant nodes

data/docs/_features/user-mentions.adoc

@@ -0,0 +1,47 @@
+---
+layout: default
+title: User Mentions
+parent: Features
+nav_order: 5
+---
+= User Mentions
+
+prosereflect supports user @mentions as a special inline node type.
+
+== Creating Mentions
+
+[source,ruby]
+----
+doc = Prosereflect::Document.create
+para = doc.add_paragraph("Hello ")
+user = Prosereflect::User.new
+user.id = "123"
+para.add_child(user)
+para.add_text("!")
+----
+
+== HTML Representation
+
+User mentions are represented as `<user-mention>` elements in HTML:
+
+[source,ruby]
+----
+html = Prosereflect::Output::Html.convert(doc)
+# includes: <user-mention data-id="123"></user-mention>
+----
+
+== Parsing from HTML
+
+[source,ruby]
+----
+html = '<p>Hello <user-mention data-id="123"></user-mention>!</p>'
+doc = Prosereflect::Input::Html.parse(html)
+users = doc.find_all('user')
+users.first.id  # => "123"
+----
+
+== Use Cases
+
+* Mentioning users in comments or messages
+* Tagging users in collaborative documents
+* Tracking user references in content

data/docs/_guides/custom-nodes.adoc

@@ -0,0 +1,107 @@
+---
+layout: default
+title: Custom Nodes
+parent: Guides
+nav_order: 2
+---
+= Custom Nodes
+
+This guide explains how to define custom node types that integrate with prosereflect's serialization and HTML conversion systems.
+
+== Defining a Custom Node
+
+Create a new class that inherits from `Prosereflect::Node`:
+
+[source,ruby]
+----
+class Callout < Prosereflect::Node
+  PM_TYPE = "callout"
+
+  # Define custom attributes
+  attribute :variant, :string
+
+  # Define serialization mapping
+  key_value do
+    map "type", to: :type, render_default: true
+    map "attrs", to: :attrs
+    map "content", to: :content
+  end
+end
+----
+
+== Key Concepts
+
+=== PM_TYPE
+
+The `PM_TYPE` constant must match the ProseMirror type string used in JSON serialization. This is how the parser maps JSON data to your Ruby class.
+
+=== Attributes
+
+Use `lutaml-model`'s `attribute` DSL to define custom attributes:
+
+[source,ruby]
+----
+attribute :variant, :string   # string attribute
+attribute :count, :integer    # integer attribute
+----
+
+Attributes are automatically included in `to_h` output when present in the `attrs` hash.
+
+=== key_value Block
+
+The `key_value` block defines how Ruby attributes map to JSON keys:
+
+[source,ruby]
+----
+key_value do
+  map "type", to: :type, render_default: true
+  map "attrs", to: :attrs
+  map "content", to: :content
+end
+----
+
+=== Convenience Methods
+
+Add helper methods for construction:
+
+[source,ruby]
+----
+class Callout < Prosereflect::Node
+  PM_TYPE = "callout"
+
+  def self.create(variant: "info", text: nil)
+    node = new(type: PM_TYPE, attrs: { "variant" => variant })
+    node.add_text(text) if text
+    node
+  end
+end
+----
+
+== Serialization Round-Trip
+
+Ensure `to_h` and `Parser` are compatible:
+
+[source,ruby]
+----
+# Serialize
+callout = Callout.create(variant: "warning", text: "Be careful!")
+hash = callout.to_h
+# => {"type" => "callout", "attrs" => {"variant" => "warning"},
+#     "content" => [{"type" => "text", "text" => "Be careful!"}]}
+
+# Deserialize (if registered with Parser)
+doc = Prosereflect::Parser.parse_document({
+  "type" => "doc",
+  "content" => [hash]
+})
+----
+
+== Node Naming Pattern
+
+prosereflect maps PM_TYPE strings to classes by convention:
+
+* `"paragraph"` -> `Prosereflect::Paragraph`
+* `"heading"` -> `Prosereflect::Heading`
+* `"table"` -> `Prosereflect::Table`
+
+Custom types follow the same pattern -- the parser uses `PM_TYPE` to find the matching class.

data/docs/_guides/index.adoc

@@ -0,0 +1,13 @@
+---
+layout: default
+title: Guides
+nav_order: 6
+has_children: true
+---
+= Guides
+
+Task-oriented tutorials for common prosereflect workflows.
+
+* x:round-trip-html[HTML Round-Trip] -- Convert between HTML and ProseMirror
+* x:custom-nodes[Custom Nodes] -- Define custom node types
+* x:serialization[Serialization] -- JSON/YAML round-trips

data/docs/_guides/round-trip-html.adoc

@@ -0,0 +1,91 @@
+---
+layout: default
+title: HTML Round-Trip
+parent: Guides
+nav_order: 1
+---
+= HTML Round-Trip
+
+This guide shows how to parse HTML into a ProseMirror document model, modify it, and convert back to HTML.
+
+== Parse HTML
+
+[source,ruby]
+----
+require 'prosereflect'
+
+html = '<p>This is <strong>bold</strong> and <em>italic</em> text.</p>'
+doc = Prosereflect::Input::Html.parse(html)
+----
+
+== Navigate and Modify
+
+[source,ruby]
+----
+# Access the first paragraph
+para = doc.paragraphs.first
+para.text_content  # => "This is bold and italic text."
+
+# Append text
+para.add_text(" More content.")
+
+# Add a new paragraph
+doc.add_paragraph("Second paragraph.")
+----
+
+== Convert Back to HTML
+
+[source,ruby]
+----
+modified_html = Prosereflect::Output::Html.convert(doc)
+----
+
+== Working with Tables
+
+[source,ruby]
+----
+html = '<table><tr><th>Header</th></tr><tr><td>Data</td></tr></table>'
+doc = Prosereflect::Input::Html.parse(html)
+
+tables = doc.tables
+first_table = tables.first
+first_table.header_row  # => row with TableHeader cells
+first_table.data_rows   # => rows with TableCell cells
+----
+
+== Round-Trip with Marks
+
+[source,ruby]
+----
+html = '<p><a href="https://example.com">click here</a></p>'
+doc = Prosereflect::Input::Html.parse(html)
+
+# The link mark is preserved
+para = doc.paragraphs.first
+
+# Convert back - links are rendered as <a> tags
+output = Prosereflect::Output::Html.convert(doc)
+----
+
+== Common Patterns
+
+=== Extract Plain Text
+
+[source,ruby]
+----
+doc = Prosereflect::Input::Html.parse(html_content)
+plain_text = doc.text_content
+----
+
+=== Find and Replace Text
+
+[source,ruby]
+----
+doc = Prosereflect::Input::Html.parse(html_content)
+
+doc.paragraphs.each do |para|
+  # Access text content
+  text = para.text_content
+  # Modify via transforms
+end
+----

data/docs/_guides/serialization.adoc

@@ -0,0 +1,109 @@
+---
+layout: default
+title: Serialization
+parent: Guides
+nav_order: 3
+---
+= Serialization
+
+prosereflect supports round-trip serialization through ProseMirror's JSON/YAML format using the `to_h` / `Parser.parse_document` methods.
+
+== to_h (Serialize)
+
+Every node can be serialized to a Ruby hash matching ProseMirror's JSON format:
+
+[source,ruby]
+----
+doc = Prosereflect::Document.create
+para = doc.add_paragraph("Hello")
+para.add_text(" bold", [Prosereflect::Mark::Bold.new])
+
+hash = doc.to_h
+# => {
+#   "type" => "doc",
+#   "content" => [
+#     {
+#       "type" => "paragraph",
+#       "content" => [
+#         { "type" => "text", "text" => "Hello" },
+#         { "type" => "text", "text" => " bold", "marks" => [{"type" => "bold"}] }
+#       ]
+#     }
+#   ]
+# }
+----
+
+== parse_document (Deserialize)
+
+Convert a ProseMirror hash back to node objects:
+
+[source,ruby]
+----
+doc = Prosereflect::Parser.parse_document(hash)
+doc.paragraphs.first.text_content  # => "Hello bold"
+----
+
+Works with YAML and JSON strings too:
+
+[source,ruby]
+----
+# From YAML
+doc = Prosereflect::Parser.parse_document(YAML.safe_load(yaml_string))
+
+# From JSON
+doc = Prosereflect::Parser.parse_document(JSON.parse(json_string))
+----
+
+== YAML Round-Trip
+
+[source,ruby]
+----
+# Serialize to YAML
+yaml = doc.to_yaml
+
+# Deserialize from YAML
+data = YAML.safe_load(yaml)
+doc = Prosereflect::Parser.parse_document(data)
+
+# Verify round-trip
+doc.to_h == original_doc.to_h  # => true
+----
+
+== JSON Round-Trip
+
+[source,ruby]
+----
+require 'json'
+
+# Serialize to JSON
+json = JSON.pretty_generate(doc.to_h)
+
+# Deserialize from JSON
+data = JSON.parse(json)
+doc = Prosereflect::Parser.parse_document(data)
+----
+
+== Step Serialization
+
+Transform steps can be serialized to JSON:
+
+[source,ruby]
+----
+step = Prosereflect::Transform::ReplaceStep.new(2, 5, slice)
+json = step.to_json
+# => {"stepType" => "replace", "from" => 2, "to" => 5, "slice" => [...]}
+
+# Deserialize
+step = Prosereflect::Transform::ReplaceStep.from_json(schema, json)
+----
+
+== to_h Behavior
+
+The `to_h` method includes:
+
+* `type` -- always included
+* `attrs` -- only if non-empty
+* `marks` -- only if non-empty
+* `content` -- only if non-empty
+
+This matches ProseMirror's JSON serialization format where omitted fields use defaults.

data/docs/_pages/index.adoc

@@ -0,0 +1,67 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+---
+= Getting Started
+
+== What is prosereflect?
+
+`prosereflect` is a Ruby gem for working with the document structure used by the https://prosemirror.net/[ProseMirror rich text editor].
+
+It provides a complete Ruby object model for ProseMirror documents, including:
+
+* Parsing and serialization (JSON, YAML, HTML)
+* A rich node hierarchy with type-safe accessors
+* A full Transform system for step-based document manipulation
+* Schema definition and content validation
+* Position resolution and mapping
+* HTML input and output with whitespace handling
+* A test builder DSL for constructing test documents
+
+== Installation
+
+Add to your Gemfile:
+
+[source,ruby]
+----
+gem 'prosereflect'
+----
+
+Or install directly:
+
+[source,sh]
+----
+gem install prosereflect
+----
+
+== Quick Example
+
+[source,ruby]
+----
+require 'prosereflect'
+
+# Create a document
+doc = Prosereflect::Document.create
+doc.add_paragraph("Hello world")
+
+# Parse from JSON hash
+doc = Prosereflect::Parser.parse_document({
+  "type" => "doc",
+  "content" => [
+    { "type" => "paragraph", "content" => [{ "type" => "text", "text" => "Hello" }] }
+  ]
+})
+
+# Parse from HTML
+doc = Prosereflect::Input::Html.parse('<p>Hello <strong>world</strong></p>')
+
+# Convert to HTML
+html = Prosereflect::Output::Html.convert(doc)
+----
+
+== Next Steps
+
+* x:features:node-types[Node Types] -- all available node types
+* x:understanding:document-model[Document Model] -- how the document tree works
+* x:guides:round-trip-html[HTML Round-Trip] -- convert between HTML and ProseMirror

data/docs/_reference/document-api.adoc

@@ -0,0 +1,49 @@
+---
+layout: default
+title: Document API
+parent: Reference
+nav_order: 2
+---
+= Document API
+
+== Prosereflect::Document
+
+Top-level document container. Inherits from Node with PM_TYPE "doc".
+
+=== Class Methods
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `Document.create(attrs)` | Create an empty document
+|===
+
+=== Query Methods
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `tables` | Find all direct child Table nodes
+| `paragraphs` | Find all direct child Paragraph nodes
+| `text_content` | Plain text from all nodes, joined by newlines
+|===
+
+=== Builder Methods
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `add_paragraph(text, attrs)` | Add a paragraph, optionally with text
+| `add_heading(level)` | Add a heading with the given level
+| `add_table(attrs)` | Add a table
+| `add_image(src, alt)` | Add an image
+| `add_bullet_list(attrs)` | Add a bullet list
+| `add_ordered_list(attrs)` | Add an ordered list
+| `add_blockquote(attrs)` | Add a blockquote
+| `add_horizontal_rule(attrs)` | Add a horizontal rule
+| `add_code_block_wrapper(attrs)` | Add a code block wrapper
+| `add_user(id)` | Add a user mention node
+|===

data/docs/_reference/index.adoc

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Reference
+nav_order: 7
+has_children: true
+---
+= Reference
+
+API reference documentation organized by module.
+
+* x:node-api[Node API] -- Node base class and Document
+* x:document-api[Document API] -- Document convenience methods
+* x:transform-api[Transform API] -- Transform and Step classes
+* x:schema-api[Schema API] -- Schema, NodeType, MarkType, ContentMatch

data/docs/_reference/node-api.adoc

@@ -0,0 +1,79 @@
+---
+layout: default
+title: Node API
+parent: Reference
+nav_order: 1
+---
+= Node API
+
+== Prosereflect::Node
+
+Base class for all document elements.
+
+=== Attributes
+
+* `type` (String) -- The node type (e.g. "doc", "paragraph", "text")
+* `attrs` (Hash) -- Node-specific attributes
+* `marks` (Array) -- Formatting marks applied to this node
+* `content` (Array) -- Child nodes
+
+=== Class Methods
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `Node.create(type, attrs)` | Create a new node with the given type and attrs
+| `Node.from_json(schema, json)` | Deserialize from JSON (requires schema)
+|===
+
+=== Instance Methods
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `node_size` | Size in document position space
+| `text?` | Whether this is a text node
+| `text_content` | Combined text of all descendant text nodes
+| `cut(from, to)` | Return a copy restricted to position range
+| `copy(content)` | Return a copy with different content
+| `add_child(node)` | Append a child node
+| `find_first(type)` | Find first descendant of type
+| `find_all(type)` | Find all descendants of type
+| `find_children(klass)` | Find direct children of class
+| `resolve(pos)` | Resolve position to ResolvedPos
+| `nodes_between(from, to, &block)` | Iterate nodes in position range
+| `descendants(&block)` | Iterate all descendant nodes
+| `eq?(other)` | Structural equality
+| `to_h` | Serialize to ProseMirror hash
+| `to_yaml` | Serialize to YAML
+|===
+
+== Prosereflect::Text
+
+Text node (PM_TYPE: "text").
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `text` | The text string
+| `node_size` | `text.length + 1`
+| `text?` | Always `true`
+|===
+
+== Prosereflect::Mark::Base
+
+Base class for all marks.
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `type` | The mark type string
+| `attrs` | Mark attributes (e.g. href for links)
+| `to_h` | Serialize to hash
+|===
+
+Mark subclasses: `Bold`, `Italic`, `Code`, `Link`, `Strike`, `Subscript`, `Superscript`, `Underline`.