prosereflect 0.1.1 → 0.3.0

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`.

data/docs/_reference/schema-api.adoc

@@ -0,0 +1,95 @@
+---
+layout: default
+title: Schema API
+parent: Reference
+nav_order: 4
+---
+= Schema API
+
+== Prosereflect::Schema
+
+=== Constructor
+
+`Schema.new(nodes_spec:, marks_spec:, top_node: nil)`
+
+[source,ruby]
+----
+schema = Prosereflect::Schema.new(
+  nodes_spec: {
+    "doc" => { content: "block+" },
+    "paragraph" => { content: "inline*", group: "block" },
+    "text" => { group: "inline" }
+  },
+  marks_spec: { "bold" => {}, "italic" => {} }
+)
+----
+
+=== Methods
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `node_type(name)` | Get NodeType by name (raises on unknown)
+| `mark_type(name)` | Get MarkType by name (raises on unknown)
+| `top_node_type` | The top-level NodeType (usually "doc")
+| `node(type, attrs, content, marks)` | Create a validated node
+| `text(text, marks)` | Create a text node
+| `mark(type, attrs)` | Create a mark
+| `node_from_json(json)` | Deserialize node from JSON
+| `mark_from_json(json)` | Deserialize mark from JSON
+|===
+
+== Schema::NodeType
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `name` | Node type name
+| `attrs` | Hash of Attribute definitions
+| `schema` | Parent Schema
+| `content_match` | ContentMatch for valid children
+| `is_block?` | Whether a block node
+| `is_inline?` | Whether an inline node
+| `is_textblock?` | Whether a block with inline content
+| `is_leaf?` | Whether a leaf node (no children)
+| `is_atom?` | Whether atomic (leaf or atom flag)
+| `text?` | Whether text type
+| `in_group?(name)` | Whether in a named group
+| `create(attrs, content, marks)` | Create node (no validation)
+| `create_checked(attrs, content, marks)` | Create with content validation
+| `create_and_fill(attrs, content, marks)` | Create with default content
+| `valid_content?(fragment)` | Check content validity
+| `allows_mark_type?(mark_type)` | Check if mark type is allowed
+|===
+
+== Schema::MarkType
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `name` | Mark type name
+| `rank` | Ordering rank
+| `schema` | Parent Schema
+| `create(attrs)` | Create a Schema::Mark instance
+| `excluded` | Set of excluded mark types
+|===
+
+== Schema::ContentMatch
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `valid_end` | Whether this is a valid terminal state
+| `match_type(node_type)` | Match a node type, returns next state or nil
+| `match_fragment(fragment)` | Match a full fragment
+| `fill_before(after:, to_end:)` | Compute filler content
+| `find_wrapping(target_type)` | Find wrapping for content
+| `inline_content?` | Whether accepts inline content
+| `default_type` | Default NodeType
+| `edge_count` | Number of edges
+| `edge(n)` | Edge at index
+|===

data/docs/_reference/transform-api.adoc

@@ -0,0 +1,77 @@
+---
+layout: default
+title: Transform API
+parent: Reference
+nav_order: 3
+---
+= Transform API
+
+== Prosereflect::Transform::Transform
+
+=== Constructor
+
+`Transform.new(doc)` -- create a transform chain for the given document.
+
+=== Step-adding Methods
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `add_mark(from, to, mark)` | Add a mark to range
+| `remove_mark(from, to, mark)` | Remove a mark from range
+| `insert(pos, content)` | Insert content at position
+| `delete(from, to)` | Delete content in range
+| `replace(from, to, slice)` | Replace range with slice
+| `replace_with(from, to, *nodes)` | Replace range with nodes
+| `set_node_attribute(pos, attrs)` | Set attributes on node at pos
+| `set_doc_attribute(attrs)` | Set document-level attributes
+| `split(pos, depth)` | Split at position
+| `join(pos, depth)` | Join nodes at position
+| `lift(range, target)` | Lift content out of wrapper
+| `wrap(range, wrappers)` | Wrap content in new nodes
+|===
+
+=== Access Methods
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `doc` | Apply steps and return resulting document
+| `steps` | Array of accumulated Step objects
+| `mapping` | The Mapping tracking position changes
+| `maps` | Array of StepMap objects
+| `size` | Number of accumulated steps
+| `empty?` | Whether no steps are accumulated
+|===
+
+=== Other Methods
+
+[cols="1,3"]
+|===
+| Method | Description
+
+| `apply` | Apply all steps (returns self)
+| `rollback` | Undo the last step
+| `clone` | Create a new Transform with same doc
+| `can_apply?` | Check if all steps can be applied
+|===
+
+== Step Types
+
+All inherit from `Prosereflect::Transform::Step`.
+
+* `ReplaceStep` -- replace range with slice
+* `ReplaceAroundStep` -- replace around a gap
+* `AddMarkStep` -- add mark to range
+* `RemoveMarkStep` -- remove mark from range
+* `AttrStep` -- set node attributes
+* `InsertStep` -- insert content at position
+* `DeleteStep` -- delete content in range
+
+== Supporting Types
+
+* `Slice` -- document slice with open boundaries
+* `StepMap` -- position mapping for a single step
+* `Mapping` -- composed position mapping across multiple steps

data/docs/_understanding/document-model.adoc

@@ -0,0 +1,65 @@
+---
+layout: default
+title: Document Model
+parent: Understanding
+nav_order: 1
+---
+= Document Model
+
+prosereflect models a ProseMirror document as a tree of Node objects. Every node has a `type`, optional `attrs`, optional `marks`, and optional `content` (child nodes).
+
+== Node Hierarchy
+
+----
+Document
+├── Paragraph
+│   ├── Text (with marks)
+│   └── Text
+├── Heading (level: 1-6)
+│   └── Text
+├── Table
+│   ├── TableRow
+│   │   ├── TableHeader
+│   │   └── TableCell
+│   │       └── Paragraph
+│   └── TableRow
+├── BulletList / OrderedList
+│   └── ListItem
+│       └── Paragraph
+├── Blockquote
+│   └── Paragraph
+├── CodeBlockWrapper
+│   └── CodeBlock
+├── Image
+├── HorizontalRule
+└── ...
+----
+
+== Node Size
+
+Each node has a `node_size` that represents its footprint in the document position space:
+
+* **Non-text nodes**: `1` (opening token) + sum of children's `node_size`
+* **Text nodes**: `text.length + 1`
+
+Example: A document with one paragraph containing "hi" has `node_size` of 5:
+
+[source,ruby]
+----
+doc.node_size  # 1 (doc) + 1 (para open) + 3 ("hi" + 1) = 5
+----
+
+== Positions
+
+Positions are integer offsets into the document tree. Position 0 is before the first child of the root. Each non-text node contributes its opening token (position +1) and its content. Text nodes contribute `text.length + 1`.
+
+[source,ruby]
+----
+# doc(p("abc"))
+# Position 0: before doc content
+# Position 1: before paragraph content
+# Position 2: before "a"
+# Position 3: between "a" and "b"
+# Position 4: between "b" and "c"
+# Position 5: after "c" (end of text)
+----

data/docs/_understanding/fragment.adoc

@@ -0,0 +1,52 @@
+---
+layout: default
+title: Fragment
+parent: Understanding
+nav_order: 2
+---
+= Fragment
+
+`Prosereflect::Fragment` represents a flat sequence of nodes. It is the primary data structure for node content and slice content.
+
+== Creating Fragments
+
+[source,ruby]
+----
+# From an array of nodes
+frag = Prosereflect::Fragment.new([node1, node2])
+
+# Empty fragment
+frag = Prosereflect::Fragment.empty
+
+# From arbitrary content
+frag = Prosereflect::Fragment.from(node)
+frag = Prosereflect::Fragment.from([node1, node2])
+frag = Prosereflect::Fragment.from(existing_fragment)  # returns as-is
+----
+
+== Core Methods
+
+* `size` -- total node_size of all contained nodes
+* `empty?` -- whether the fragment has no nodes
+* `length` / `count` -- number of nodes
+* `to_a` -- convert to a plain array
+* `each` -- iterate over nodes
+* `[](index)` -- access node by index
+
+== Manipulation
+
+* `append(other)` -- concatenate two fragments (returns new Fragment)
+* `cut(from, to)` -- extract a sub-fragment within position range
+* `replace_child(index, replacement)` -- replace a node at index
+
+== Traversal
+
+* `nodes_between(from, to, &block)` -- iterate nodes within position range, callback receives `(node, position)`
+* `descendants(&block)` -- iterate all descendant nodes
+* `text_between(from, to)` -- extract text between positions
+
+== Comparison
+
+* `eq?(other)` -- structural equality check
+* `find_diff_start(other)` -- find first position where two fragments differ
+* `find_diff_end(other)` -- find last position where two fragments differ