prosereflect 0.1.1 → 0.3.0

data/Gemfile

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in prosereflect.gemspec
 gemspec
 
-gem 'rake'
-gem 'rspec'
-gem 'rubocop'
+gem "lutaml-model", github: "lutaml/lutaml-model", branch: "main"
+gem "rake"
+gem "rspec"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rake"
+gem "rubocop-rspec"

data/README.adoc

@@ -14,6 +14,8 @@ accessing the hierarchical document tree structure represented in ProseMirror's
 JSON/YAML format. This allows for convenient traversal and extraction of content
 from rich text documents.
 
+https://metanorma.org/prosereflect/[Full documentation] is available on the docs site.
+
 
 == Installation
 

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-require 'rubocop/rake_task'
+require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 

data/docs/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "jekyll-asciidoc"
+gem "just-the-docs"
+
+group :jekyll_plugins do
+  gem "jekyll-seo-tag"
+  gem "jekyll-sitemap"
+end

data/docs/INDEX.adoc

@@ -0,0 +1,45 @@
+---
+layout: default
+title: Home
+nav_order: 1
+---
+
+= Prosereflect Documentation
+
+`prosereflect` is a Ruby gem for working with the document structure used by the https://prosemirror.net/[ProseMirror rich text editor].
+
+It provides a set of models and utilities for parsing, manipulating, and accessing the hierarchical document tree structure represented in ProseMirror's JSON/YAML format.
+
+== Quick Start
+
+Install the gem:
+
+[source,sh]
+----
+gem install prosereflect
+----
+
+Parse a document:
+
+[source,ruby]
+----
+require 'prosereflect'
+
+doc = Prosereflect::Parser.parse_document({
+  "type" => "doc",
+  "content" => [
+    { "type" => "paragraph", "content" => [{ "type" => "text", "text" => "Hello world" }] }
+  ]
+})
+----
+
+== Documentation Sections
+
+* x:features:node-types[Node Types] -- All available node types and their attributes
+* x:features:marks[Marks] -- Text formatting marks (bold, italic, links, etc.)
+* x:understanding:document-model[Document Model] -- Node hierarchy and content model
+* x:understanding:fragment[Fragment] -- Flat content collections
+* x:understanding:resolved-position[Resolved Positions] -- Position resolution in the document tree
+* x:advanced:transform[Transforms] -- Document transformations and step-based editing
+* x:advanced:schema[Schema] -- Schema definition and validation
+* x:guides:round-trip-html[HTML Round-Trip] -- Convert between HTML and ProseMirror documents

data/docs/_advanced/index.adoc

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Advanced
+nav_order: 5
+has_children: true
+---
+= Advanced
+
+This section covers advanced topics for power users.
+
+* x:transform[Transforms] -- Step-based document transformations
+* x:steps[Step Types] -- Individual step types and their behavior
+* x:step-map[Step Maps and Mappings] -- Position tracking through transforms
+* x:schema[Schema] -- Schema definition and content validation
+* x:test-builder[Test Builder] -- DSL for building test documents

data/docs/_advanced/schema.adoc

@@ -0,0 +1,112 @@
+---
+layout: default
+title: Schema
+parent: Advanced
+nav_order: 4
+---
+= Schema
+
+`Prosereflect::Schema` defines the structure of valid documents: which node types exist, what content they can contain, and which marks are allowed.
+
+== Creating a Schema
+
+[source,ruby]
+----
+schema = Prosereflect::Schema.new(
+  nodes_spec: {
+    "doc" => { content: "block+" },
+    "paragraph" => { content: "inline*", group: "block" },
+    "heading" => { content: "inline*", group: "block", attrs: { "level" => { "default" => 1 } } },
+    "text" => { group: "inline" }
+  },
+  marks_spec: {
+    "bold" => {},
+    "italic" => {},
+    "link" => { attrs: { "href" => {} } }
+  }
+)
+----
+
+== Requirements
+
+Every schema must define:
+
+* A `"doc"` node type (the top-level container)
+* A `"text"` node type (inline text)
+* At least one block node type in the doc's content expression
+
+== Content Expressions
+
+Content expressions define what children a node can have. Supported syntax:
+
+* `"block+"` -- one or more block nodes
+* `"inline*"` -- zero or more inline nodes
+* `"paragraph heading"` -- a paragraph followed by a heading
+* `"(paragraph | heading)"` -- either paragraph or heading
+* `"block{2,4}"` -- between 2 and 4 block nodes
+* `"block?"` -- optional block node
+
+== NodeType
+
+Access and use node types from a schema:
+
+[source,ruby]
+----
+para_type = schema.node_type("paragraph")
+para_type.name             # => "paragraph"
+para_type.is_block?        # => true
+para_type.is_inline?       # => false
+para_type.is_textblock?    # => true
+para_type.is_leaf?         # => false
+para_type.is_atom?         # => false
+----
+
+Creating validated nodes:
+
+[source,ruby]
+----
+# Create with validation
+node = para_type.create_checked(nil, [text_node])
+
+# Create with defaults
+node = para_type.create_and_fill
+
+# Check content validity
+para_type.valid_content?(fragment)
+----
+
+== MarkType
+
+Access and use mark types:
+
+[source,ruby]
+----
+bold_type = schema.mark_type("bold")
+mark = bold_type.create      # Schema::Mark instance
+mark.attrs                  # => {}
+
+link_type = schema.mark_type("link")
+link = link_type.create("href" => "https://example.com")
+link.attrs  # => {"href" => "https://example.com"}
+----
+
+== ContentMatch
+
+`ContentMatch` is the engine that validates content expressions. It uses an NFA/DFA approach to parse and match content expressions:
+
+* `match_type(node_type)` -- try to match a node type, returns next match state or nil
+* `match_fragment(fragment)` -- match a full fragment
+* `valid_end` -- whether this state is a valid end state
+* `fill_before(after:, to_end:)` -- compute filler content
+* `find_wrapping(target_type)` -- find wrapping nodes for content
+* `inline_content?` -- whether this match accepts inline content
+* `default_type` -- the default node type for this match
+
+== Validation Errors
+
+The schema raises `Prosereflect::SchemaErrors::ValidationError` for:
+
+* Missing required node types (doc, text)
+* Name collisions between nodes and marks
+* Invalid content in created nodes
+* Missing required attributes

data/docs/_advanced/step-map.adoc

@@ -0,0 +1,66 @@
+---
+layout: default
+title: Step Maps and Mappings
+parent: Advanced
+nav_order: 3
+---
+= Step Maps and Mappings
+
+When steps are applied to a document, positions in the original document may no longer correspond to the same locations. Step maps and mappings track these changes.
+
+== StepMap
+
+`Prosereflect::Transform::StepMap` maps positions through a single step. It stores an array of ranges `[old_start, old_end, new_start, new_end]`.
+
+[source,ruby]
+----
+# Create a step map
+map = Prosereflect::Transform::StepMap.new([[0, 5, 0, 8]])
+
+# Map a position
+map.map(3)  # => new position after the step
+
+# Check if a position was deleted
+map.deleted?(3)  # => true/false
+
+# Map with deletion info
+result = map.map_result(3)
+result.pos       # => new position
+result.deleted   # => whether the position was deleted
+result.transformed  # => whether the position changed
+----
+
+=== Factory Methods
+
+* `StepMap.empty` -- identity map (no changes)
+* `StepMap.delete(from, to)` -- map for a deletion
+* `StepMap.replace(from, to, target_from, target_to)` -- map for a replacement
+
+== Mapping
+
+`Prosereflect::Transform::Mapping` composes multiple step maps to track positions through a full transform chain.
+
+[source,ruby]
+----
+mapping = Prosereflect::Transform::Mapping.new
+mapping.add_map(step_map_1)
+mapping.add_map(step_map_2)
+
+# Map a position through all steps
+mapping.map(5)  # => final position
+
+# Map with deletion tracking
+result = mapping.map_result(5)
+result[:pos]       # => final position
+result[:deleted]   # => whether deleted by any step
+
+# Map backwards
+mapping.map_reverse(8)  # => original position
+----
+
+=== Checking Deletions
+
+[source,ruby]
+----
+mapping.map_deletes(5)  # => whether position 5 was deleted by any step
+----

data/docs/_advanced/steps.adoc

@@ -0,0 +1,88 @@
+---
+layout: default
+title: Step Types
+parent: Advanced
+nav_order: 2
+---
+= Step Types
+
+Each step is an atomic document change. All steps inherit from `Prosereflect::Transform::Step`.
+
+== Step Base Class
+
+Every step implements:
+
+* `apply(doc)` -- apply to a document, returns `Result` (ok/fail)
+* `get_map` -- returns a `StepMap` for position tracking
+* `invert(doc)` -- returns a step that undoes this one
+* `merge(other)` -- optionally merge with another step (returns nil if not possible)
+* `to_json` -- serialize to JSON
+* `step_type` -- string identifier for the step type
+
+== ReplaceStep
+
+Replaces a range of content with a slice:
+
+[source,ruby]
+----
+step = Prosereflect::Transform::ReplaceStep.new(from, to, slice)
+result = step.apply(doc)
+# step_type: "replace"
+----
+
+== ReplaceAroundStep
+
+Replaces content while preserving a "gap" -- used by lift and wrap operations:
+
+[source,ruby]
+----
+step = Prosereflect::Transform::ReplaceAroundStep.new(
+  from, to, gap_from, gap_to, slice, insert, structure: false
+)
+# step_type: "replaceAround"
+----
+
+The `structure` flag prevents the step from overwriting content in the non-gap range.
+
+== AddMarkStep / RemoveMarkStep
+
+Add or remove a mark over a range:
+
+[source,ruby]
+----
+add_step = Prosereflect::Transform::AddMarkStep.new(from, to, mark)
+remove_step = Prosereflect::Transform::RemoveMarkStep.new(from, to, mark)
+# step_types: "addMark", "removeMark"
+----
+
+== AttrStep
+
+Set attributes on a node at a position:
+
+[source,ruby]
+----
+step = Prosereflect::Transform::AttrStep.new(pos, { "level" => 3 })
+# step_type: "attr"
+----
+
+== InsertStep / DeleteStep
+
+Insert or delete content at a position:
+
+[source,ruby]
+----
+insert_step = Prosereflect::Transform::InsertStep.new(pos, content)
+delete_step = Prosereflect::Transform::DeleteStep.new(from, to)
+----
+
+== Result
+
+`Step::Result` indicates success or failure:
+
+[source,ruby]
+----
+result = step.apply(doc)
+result.ok?     # => true if successful
+result.doc     # => the new document (on success)
+result.failed  # => error message (on failure)
+----

data/docs/_advanced/test-builder.adoc

@@ -0,0 +1,61 @@
+---
+layout: default
+title: Test Builder
+parent: Advanced
+nav_order: 5
+---
+= Test Builder
+
+`TestBuilder` provides a DSL for constructing ProseMirror documents in tests, inspired by ProseMirror's test-builder.
+
+== Basic Usage
+
+[source,ruby]
+----
+require 'prosereflect/test_builder'
+
+# Parse a document from DSL notation
+doc = TestBuilder.parse('doc(p("hello world"))')
+----
+
+== DSL Syntax
+
+The DSL uses function-call syntax to build document trees:
+
+* `doc(...)` -- document node
+* `p(...)` -- paragraph node
+* `h1(...)` through `h6(...)` -- heading nodes
+* `text(...)` -- text node
+* `table(...)` -- table node
+* `ul(...)` / `ol(...)` -- list nodes
+
+Strings in quotes become text nodes:
+
+[source,ruby]
+----
+doc(p("hello"))                    # paragraph with text
+doc(p("hello ", bold("world")))    # paragraph with bold text
+----
+
+== Position Markers
+
+Insert markers to track positions in tests:
+
+* `<|>` -- cursor position
+* `<|name>` -- named anchor
+* `<1>` -- numbered position
+
+[source,ruby]
+----
+content, positions = TestBuilder.extract_markers('doc(p("hello<|a> world<|b>"))')
+positions["a"]  # => position of first marker
+positions["b"]  # => position of second marker
+----
+
+== Schema Integration
+
+[source,ruby]
+----
+builder = TestBuilder.for_schema(schema)
+doc = builder.parse('doc(p("hello"))')
+----

data/docs/_advanced/transform.adoc

@@ -0,0 +1,92 @@
+---
+layout: default
+title: Transforms
+parent: Advanced
+nav_order: 1
+---
+= Transforms
+
+`Prosereflect::Transform::Transform` provides a chainable API for composing document changes as a sequence of steps. Each transform accumulates steps and their position mappings.
+
+== Creating a Transform
+
+[source,ruby]
+----
+doc = Prosereflect::Parser.parse_document(data)
+tx = Prosereflect::Transform::Transform.new(doc)
+----
+
+== Operations
+
+=== Adding and Removing Marks
+
+[source,ruby]
+----
+mark = Prosereflect::Mark::Bold.new
+tx.add_mark(1, 4, mark)      # Bold text from position 1 to 4
+tx.remove_mark(1, 4, mark)   # Remove bold from position 1 to 4
+----
+
+=== Inserting and Deleting
+
+[source,ruby]
+----
+tx.insert(5, some_content)   # Insert content at position 5
+tx.delete(2, 7)              # Delete content from position 2 to 7
+----
+
+=== Replacing
+
+[source,ruby]
+----
+slice = Prosereflect::Transform::Slice.new(fragment)
+tx.replace(2, 7, slice)      # Replace positions 2-7 with slice content
+tx.replace_with(2, 7, node)  # Replace positions 2-7 with nodes
+----
+
+=== Structural Operations
+
+[source,ruby]
+----
+tx.split(5)        # Split the document at position 5
+tx.join(5)         # Join two nodes at position 5
+tx.lift(range, target_depth)   # Lift content out of wrapper
+tx.wrap(range, wrappers)       # Wrap content in new nodes
+----
+
+=== Setting Attributes
+
+[source,ruby]
+----
+tx.set_node_attribute(pos, { "level" => 3 })
+tx.set_doc_attribute({ "meta" => "value" })
+----
+
+== Applying Transforms
+
+[source,ruby]
+----
+# Apply all steps and get the resulting document
+new_doc = tx.doc
+
+# Check step count
+tx.size   # => number of accumulated steps
+tx.empty? # => whether any steps exist
+----
+
+== Mappings
+
+Each step records a `StepMap` describing how positions change. The transform's `mapping` tracks all maps:
+
+[source,ruby]
+----
+tx.maps    # => array of StepMap objects
+tx.mapping.map(pos)  # => map a position through all steps
+----
+
+== Rollback
+
+[source,ruby]
+----
+tx.rollback  # Undo the last step
+----