prosereflect 0.2.0 → 0.3.0

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
+----

data/docs/_config.yml

@@ -0,0 +1,174 @@
+# Jekyll configuration for Prosereflect documentation
+# Uses Just the Docs theme - https://just-the-docs.com/
+
+# Site settings
+title: Prosereflect Documentation
+description: Ruby library for parsing, manipulating, and traversing ProseMirror rich text editor document trees
+url: https://metanorma.org
+baseurl: /prosereflect
+
+# Repository
+repository: metanorma/prosereflect
+
+# Theme
+theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs@v0.7.0
+color_scheme: light
+
+# AsciiDoc support
+asciidoc: {}
+asciidoctor:
+  attributes:
+    idprefix: ''
+    idseparator: '-'
+    source-highlighter: rouge
+    icons: font
+    experimental: true
+    sectanchors: true
+    linkattrs: true
+    sectnums: true
+    toc: left
+    toclevels: 3
+
+# Search configuration
+search_enabled: true
+search:
+  heading_level: 3
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: true
+
+# Navigation
+nav_sort: case_insensitive
+nav_fold: true
+
+# External links
+aux_links:
+  "Source":
+    - "https://github.com/metanorma/prosereflect"
+  "Report Issues":
+    - "https://github.com/metanorma/prosereflect/issues"
+
+aux_links_new_tab: true
+
+# Back to top
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Heading anchors
+heading_anchors: true
+
+# Footer
+footer_content: 'Copyright &copy; 2025 Ribose. Distributed under the <a href="https://github.com/metanorma/prosereflect/blob/main/LICENSE">BSD 2-Clause License</a>.'
+
+# Footer last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Enable code copy button
+enable_copy_code_button: true
+
+# Callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
+# Plugins
+plugins:
+  - jekyll-asciidoc
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# Markdown settings (for any markdown files)
+markdown: kramdown
+kramdown:
+  input: GFM
+  hard_wrap: false
+  syntax_highlighter: rouge
+
+# Collections for organizing content
+collections:
+  pages:
+    permalink: "/:path/"
+    output: true
+  features:
+    permalink: "/:collection/:path/"
+    output: true
+  understanding:
+    permalink: "/:collection/:path/"
+    output: true
+  advanced:
+    permalink: "/:collection/:path/"
+    output: true
+  guides:
+    permalink: "/:collection/:path/"
+    output: true
+  reference:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Just the Docs collection configuration
+just_the_docs:
+  collections:
+    pages:
+      name: Pages
+      nav_fold: false
+    features:
+      name: Features
+      nav_fold: true
+    understanding:
+      name: Understanding
+      nav_fold: true
+    advanced:
+      name: Advanced
+      nav_fold: true
+    guides:
+      name: Guides
+      nav_fold: true
+    reference:
+      name: Reference
+      nav_fold: true
+
+# Defaults
+defaults:
+  - scope:
+      path: ""
+      type: pages
+    values:
+      layout: default
+
+# Include additional files
+include:
+  - "*.adoc"
+
+# Exclude from processing
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - node_modules
+  - vendor
+  - .sass-cache
+  - .jekyll-cache
+  - .bundle
+  - README.md
+  - LICENSE
+  - .git
+  - .gitignore
+
+permalink: pretty

data/docs/_features/html-input.adoc

@@ -0,0 +1,69 @@
+---
+layout: default
+title: HTML Input
+parent: Features
+nav_order: 3
+---
+= HTML Input
+
+`Prosereflect::Input::Html` parses HTML strings into ProseMirror document models using Nokogiri.
+
+== Basic Parsing
+
+[source,ruby]
+----
+require 'prosereflect'
+
+html = '<p>Hello <strong>bold</strong> and <em>italic</em></p>'
+doc = Prosereflect::Input::Html.parse(html)
+
+para = doc.paragraphs.first
+para.text_content  # => "Hello bold and italic"
+----
+
+== Supported Elements
+
+The HTML parser maps standard HTML elements to ProseMirror node types:
+
+[cols="2,2"]
+|===
+| HTML | ProseMirror Type
+
+| `<p>` | paragraph
+| `<h1>` - `<h6>` | heading (with level attr)
+| `<ul>` / `<ol>` | bullet_list / ordered_list
+| `<li>` | list_item
+| `<table>`, `<tr>`, `<td>`, `<th>` | table, table_row, table_cell, table_header
+| `<blockquote>` | blockquote
+| `<pre><code>` | code_block_wrapper / code_block
+| `<img>` | image
+| `<hr>` | horizontal_rule
+| `<br>` | hard_break
+| `<user-mention>` | user
+|===
+
+== Supported Inline Formatting
+
+[cols="2,2"]
+|===
+| HTML | Mark Type
+
+| `<strong>`, `<b>` | bold
+| `<em>`, `<i>` | italic
+| `<code>` | code
+| `<a>` | link (with href)
+| `<s>`, `<del>` | strike
+| `<sub>` | subscript
+| `<sup>` | superscript
+| `<u>` | underline
+|===
+
+== User Mentions
+
+[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"
+----

data/docs/_features/html-output.adoc

@@ -0,0 +1,45 @@
+---
+layout: default
+title: HTML Output
+parent: Features
+nav_order: 4
+---
+= HTML Output
+
+`Prosereflect::Output::Html` converts ProseMirror document models to HTML strings using Nokogiri.
+
+== Basic Conversion
+
+[source,ruby]
+----
+require 'prosereflect'
+
+doc = Prosereflect::Document.create
+para = doc.add_paragraph("Hello")
+para.add_text(" bold", [Prosereflect::Mark::Bold.new])
+
+html = Prosereflect::Output::Html.convert(doc)
+# => "<html><body><p>Hello<strong> bold</strong></p></body></html>"
+----
+
+== DOMSerializer
+
+`Prosereflect::Output::DOMSerializer` provides fine-grained control over HTML output:
+
+* `serialize_node(node)` -- serialize a single node
+* `render_text(text, marks)` -- render text with marks applied
+
+== Whitespace Handling
+
+The serializer handles whitespace differently depending on the parent node type:
+
+* **Code blocks** (`code_block`, `code_block_wrapper`): whitespace is preserved exactly
+* **Regular blocks** (`paragraph`, `heading`): whitespace is collapsed (multiple spaces become one)
+* **`white-space: pre`** nodes: whitespace is preserved
+
+Methods involved:
+
+* `whitespace_mode(node)` -- returns `:preserve` or `:collapse`
+* `collapse_whitespace(text)` -- collapses runs of whitespace
+* `normalize_whitespace(text)` -- replaces tabs/newlines with spaces
+* `process_text_whitespace(text, node)` -- applies the appropriate mode

data/docs/_features/index.adoc

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Features
+nav_order: 3
+has_children: true
+---
+= Features
+
+prosereflect provides a comprehensive set of features for working with ProseMirror documents in Ruby.
+
+* x:node-types[Node Types] -- All available node types and their attributes
+* x:marks[Marks] -- Text formatting marks (bold, italic, links, etc.)
+* x:html-input[HTML Input] -- Parse HTML into ProseMirror documents
+* x:html-output[HTML Output] -- Serialize documents to HTML
+* x:user-mentions[User Mentions] -- @mention support in documents

data/docs/_features/marks.adoc

@@ -0,0 +1,86 @@
+---
+layout: default
+title: Marks
+parent: Features
+nav_order: 2
+---
+= Marks
+
+Marks represent inline formatting applied to text nodes. prosereflect supports all standard ProseMirror marks.
+
+== Creating Marks
+
+[source,ruby]
+----
+bold = Prosereflect::Mark::Bold.new
+italic = Prosereflect::Mark::Italic.new
+link = Prosereflect::Mark::Link.new(href: "https://example.com")
+----
+
+== Applying Marks to Text
+
+When adding text to a node, pass marks as the second argument:
+
+[source,ruby]
+----
+doc = Prosereflect::Document.create
+para = doc.add_paragraph("Plain text")
+para.add_text(" bold", [Prosereflect::Mark::Bold.new])
+para.add_text(" italic", [Prosereflect::Mark::Italic.new])
+para.add_text(" both", [Prosereflect::Mark::Bold.new, Prosereflect::Mark::Italic.new])
+----
+
+== Available Mark Types
+
+[cols="1,1,3"]
+|===
+| Class | PM Type | Attributes
+
+| `Mark::Bold` | `bold` | none
+| `Mark::Italic` | `italic` | none
+| `Mark::Code` | `code` | none
+| `Mark::Link` | `link` | `href`
+| `Mark::Strike` | `strike` | none
+| `Mark::Subscript` | `subscript` | none
+| `Mark::Superscript` | `superscript` | none
+| `Mark::Underline` | `underline` | none
+|===
+
+== Link Marks
+
+Link marks carry an `href` attribute:
+
+[source,ruby]
+----
+link_mark = Prosereflect::Mark::Link.new
+link_mark.href = "https://example.com"
+# or via constructor:
+link_mark = Prosereflect::Mark::Link.new(href: "https://example.com")
+----
+
+== Serialization
+
+Marks are serialized in the ProseMirror JSON format:
+
+[source,ruby]
+----
+bold = Prosereflect::Mark::Bold.new
+bold.to_h  # => {"type" => "bold"}
+
+link = Prosereflect::Mark::Link.new(href: "https://example.com")
+link.to_h  # => {"type" => "link", "attrs" => {"href" => "https://example.com"}}
+----
+
+== Schema-based Marks
+
+When using a Schema, marks can be created with validation:
+
+[source,ruby]
+----
+schema = Prosereflect::Schema.new(
+  nodes_spec: { "doc" => { content: "block+" }, "paragraph" => { content: "inline*", group: "block" }, "text" => { group: "inline" } },
+  marks_spec: { "bold" => {}, "italic" => {} }
+)
+bold = schema.mark("bold")
+italic = schema.mark("italic")
+----