prosereflect 0.1.1 → 0.3.0

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

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