prosereflect 0.1.1 → 0.3.0

data/docs/_understanding/index.adoc

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Understanding
+nav_order: 4
+has_children: true
+---
+= Understanding
+
+This section explains the core concepts behind prosereflect's document model.
+
+* x:document-model[Document Model] -- Node hierarchy and content model
+* x:fragment[Fragment] -- Flat content collections
+* x:resolved-position[Resolved Positions] -- Position resolution in the document tree
+* x:slice[Slice] -- Document slices with open boundaries

data/docs/_understanding/resolved-position.adoc

@@ -0,0 +1,53 @@
+---
+layout: default
+title: Resolved Positions
+parent: Understanding
+nav_order: 3
+---
+= Resolved Positions
+
+`Prosereflect::ResolvedPos` represents a document position that has been resolved to a specific location in the document tree. Resolving a position gives you information about the surrounding context.
+
+== Creating a ResolvedPos
+
+[source,ruby]
+----
+doc = Prosereflect::Parser.parse_document(data)
+resolved = doc.resolve(3)
+----
+
+== Properties
+
+* `pos` -- the absolute document position
+* `depth` -- how deep in the tree this position is (0 = root)
+* `parent` -- the parent node at current depth
+* `parent_offset` -- offset within the parent node (`pos - start`)
+
+== Depth-based Access
+
+These methods accept an optional `depth` parameter (default: current depth):
+
+* `node(depth)` -- node at the given depth
+* `index(depth)` -- index within parent at depth
+* `start(depth)` -- start position of node at depth
+* `end_(depth)` -- end position of node at depth
+
+== Boundary Checks
+
+* `block?` -- whether the parent is a block node
+* `inline?` -- whether the parent is an inline node
+* `text_block?` -- whether the parent is a text block
+* `start_of_parent?` -- whether at start of parent
+* `end_of_parent?` -- whether at end of parent
+* `before?` -- whether at the start of the current node
+* `after?` -- whether at the end of the current node
+
+== Comparing Positions
+
+* `shared_depth(other)` -- the deepest depth shared with another position
+* `block_range(other)` -- create a NodeRange between two positions
+
+== Marks
+
+* `marks` -- marks at this position
+* `marks_between(from, to, marks)` -- collect marks between positions

data/docs/_understanding/slice.adoc

@@ -0,0 +1,54 @@
+---
+layout: default
+title: Slice
+parent: Understanding
+nav_order: 4
+---
+= Slice
+
+`Prosereflect::Transform::Slice` represents a contiguous portion of a document that can be inserted, deleted, or moved. Slices track "open" boundaries for proper node joining during replacements.
+
+== Creating Slices
+
+[source,ruby]
+----
+# From a fragment
+slice = Prosereflect::Transform::Slice.new(fragment)
+
+# With open boundaries
+slice = Prosereflect::Transform::Slice.new(fragment, open_start: 1, open_end: 1)
+
+# Empty slice
+slice = Prosereflect::Transform::Slice.empty
+----
+
+== Open Boundaries
+
+`open_start` and `open_end` indicate how many levels of the slice's first/last nodes are "open" (not included in the content). This is used when splitting or joining nodes during transforms:
+
+* `open_start = 0` -- the first node is complete
+* `open_start = 1` -- the first node is open at the top (its content extends beyond the slice)
+
+== Properties
+
+* `content` -- the `Fragment` containing the slice's nodes
+* `open_start` -- number of open levels at the start
+* `open_end` -- number of open levels at the end
+* `size` -- total size including open boundaries (`content_size + open_start + open_end`)
+* `content_size` -- size of just the content fragment
+* `empty?` -- whether the slice has no content and no open boundaries
+
+== Methods
+
+* `cut(from, to)` -- return a sub-slice
+* `eq?(other)` -- structural equality check
+
+== Use in Transforms
+
+Slices are used as the replacement content in `ReplaceStep` and `ReplaceAroundStep`:
+
+[source,ruby]
+----
+tx = Prosereflect::Transform::Transform.new(doc)
+tx.replace(2, 5, Prosereflect::Transform::Slice.new(fragment))
+----

data/docs/lychee.toml

@@ -0,0 +1,63 @@
+# Lychee Link Checker Configuration
+# For Prosereflect Documentation
+# https://github.com/lycheeverse/lychee
+
+# Cache results to avoid re-checking same URLs
+cache = true
+max_cache_age = "1d"
+
+# Check both source files and built site
+include_verbatim = true
+
+# File types to check (regex patterns)
+include = [
+  "_site/**/*.html",
+  ".*\\.adoc$",
+  ".*\\.md$"
+]
+
+# Excluded paths
+exclude = [
+  ".git",
+  ".github",
+  "node_modules",
+  "vendor",
+  ".bundle",
+  ".sass-cache",
+  ".jekyll-cache",
+  "_site/.jekyll-cache",
+  "Gemfile.lock"
+]
+
+# Link checking behavior
+max_redirects = 10
+max_retries = 3
+timeout = 30
+
+# Accept status codes
+accept = [
+  "100..=103",  # Informational
+  "200..=299",  # Success
+  "429"         # Too Many Requests (retry handled by max_retries)
+]
+
+# User agent to identify ourselves
+user_agent = "lychee/prosereflect-docs-link-checker"
+
+# Check HTTP, HTTPS, and file:// schemes
+scheme = ["https", "http", "file"]
+
+# Handle different link types
+include_mail = false  # Don't check mailto: links
+
+# Maximum concurrent requests
+max_concurrency = 10
+
+# Verbose output for debugging
+verbose = "warn"
+
+# Require HTTPS where possible
+require_https = false  # Don't enforce
+
+# Index files for directory URLs
+index_files = ["index.html"]

data/lib/prosereflect/attribute/base.rb

@@ -1,24 +1,22 @@
 # frozen_string_literal: true
 
-require_relative '../attribute'
-
 module Prosereflect
   module Attribute
     class Base < Lutaml::Model::Serializable
-      PM_TYPE = 'attribute'
+      PM_TYPE = "attribute"
 
       attribute :type, :string, default: lambda {
         begin
           self.class.const_get(:PM_TYPE)
         rescue StandardError
-          'attribute'
+          "attribute"
         end
       }
       attribute :value, :string
 
       key_value do
-        map 'type', to: :type, render_default: true
-        map 'value', to: :value
+        map "type", to: :type, render_default: true
+        map "value", to: :value
       end
 
       def self.create(type, value)

data/lib/prosereflect/attribute/bold.rb

@@ -1,15 +1,13 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-
 module Prosereflect
   module Attribute
     class Bold < Base
-      PM_TYPE = 'bold'
+      PM_TYPE = "bold"
 
       def initialize(options = {})
         super
-        self.type = 'bold'
+        self.type = "bold"
       end
 
       def attrs

data/lib/prosereflect/attribute/href.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-
 module Prosereflect
   module Attribute
     class Href < Base
-      PM_TYPE = 'href'
+      PM_TYPE = "href"
 
       attribute :type, :string, default: -> { PM_TYPE }
       attribute :href, :string

data/lib/prosereflect/attribute/id.rb

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-
 module Prosereflect
   module Attribute
     class Id < Base
-      PM_TYPE = 'id'
+      PM_TYPE = "id"
 
-      attribute :type, :string, default: -> { send('const_get', 'PM_TYPE') }
+      attribute :type, :string, default: -> {
+        self.class.send(:const_get, "PM_TYPE")
+      }
       attribute :id, :string
 
       key_value do
-        map 'type', to: :type, render_default: true
-        map 'id', to: :id
+        map "type", to: :type, render_default: true
+        map "id", to: :id
       end
 
       # Convert to hash for serialization
       def to_h
-        { 'id' => id }
+        { "id" => id }
       end
     end
   end

data/lib/prosereflect/attribute.rb

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
 
-require 'lutaml/model'
-
 module Prosereflect
   module Attribute
+    autoload :Base, "#{__dir__}/attribute/base"
+    autoload :Href, "#{__dir__}/attribute/href"
+    autoload :Id, "#{__dir__}/attribute/id"
+    autoload :Bold, "#{__dir__}/attribute/bold"
   end
 end
-
-require_relative 'attribute/base'
-require_relative 'attribute/href'
-require_relative 'attribute/id'
-require_relative 'attribute/bold'

data/lib/prosereflect/blockquote.rb

@@ -1,21 +1,20 @@
 # frozen_string_literal: true
 
-require_relative 'node'
-require_relative 'paragraph'
-
 module Prosereflect
   # It can contain other block-level content like paragraphs, lists, etc.
   class Blockquote < Node
-    PM_TYPE = 'blockquote'
+    PM_TYPE = "blockquote"
 
-    attribute :type, :string, default: -> { send('const_get', 'PM_TYPE') }
+    attribute :type, :string, default: -> {
+      self.class.send(:const_get, "PM_TYPE")
+    }
     attribute :citation, :string
     attribute :attrs, :hash
 
     key_value do
-      map 'type', to: :type, render_default: true
-      map 'content', to: :content
-      map 'attrs', to: :attrs
+      map "type", to: :type, render_default: true
+      map "content", to: :content
+      map "attrs", to: :attrs
     end
 
     def initialize(attributes = {})
@@ -56,12 +55,12 @@ module Prosereflect
     # Update citation/source for the blockquote
     def citation=(source)
       self.attrs ||= {}
-      attrs['citation'] = source
+      attrs["citation"] = source
     end
 
     # Get citation/source of the blockquote
     def citation
-      attrs&.[]('citation')
+      attrs&.[]("citation")
     end
 
     # Check if blockquote has a citation
@@ -72,7 +71,16 @@ module Prosereflect
     # Remove citation
     def remove_citation
       self.attrs ||= {}
-      attrs.delete('citation')
+      attrs.delete("citation")
+    end
+
+    def to_h
+      hash = super
+      if hash["attrs"]&.key?("citation") && hash["attrs"]["citation"].nil?
+        hash["attrs"].delete("citation")
+        hash.delete("attrs") if hash["attrs"].empty?
+      end
+      hash
     end
 
     def add_paragraph(text)

data/lib/prosereflect/bullet_list.rb

@@ -1,41 +1,42 @@
 # frozen_string_literal: true
 
-require_relative 'node'
-require_relative 'list_item'
-
 module Prosereflect
   # BulletList class represents an unordered list in ProseMirror.
   class BulletList < Node
-    PM_TYPE = 'bullet_list'
+    PM_TYPE = "bullet_list"
 
-    attribute :type, :string, default: -> { send('const_get', 'PM_TYPE') }
+    attribute :type, :string, default: -> {
+      self.class.send(:const_get, "PM_TYPE")
+    }
     attribute :bullet_style, :string
     attribute :attrs, :hash
 
     key_value do
-      map 'type', to: :type, render_default: true
-      map 'attrs', to: :attrs
-      map 'content', to: :content
+      map "type", to: :type, render_default: true
+      map "attrs", to: :attrs
+      map "content", to: :content
     end
 
     def initialize(attributes = {})
       attributes[:content] ||= []
-      attributes[:attrs] ||= { 'bullet_style' => nil }
+      # Only apply default if attrs key is completely absent
+      unless attributes.key?(:attrs) || attributes.key?("attrs")
+        attributes[:attrs] = { "bullet_style" => nil }
+      end
       super
     end
 
-    def self.create(attrs = nil)
-      new(attrs: attrs)
-    end
-
-    def bullet_style=(value)
-      @bullet_style = value
-      self.attrs ||= {}
-      attrs['bullet_style'] = value
-    end
-
-    def bullet_style
-      @bullet_style || attrs&.[]('bullet_style')
+    # Use *args to distinguish between create (no args) and create(nil)
+    # create with no args -> defaults applied
+    # create(nil) from parser -> no defaults, attrs explicitly nil
+    def self.create(*args)
+      if args.empty?
+        # No attrs provided - let initialize apply defaults
+        new(type: PM_TYPE)
+      else
+        attrs = args[0]
+        new({ type: PM_TYPE, attrs: attrs })
+      end
     end
 
     def add_item(text)
@@ -67,17 +68,23 @@ module Prosereflect
 
     # Get text content with proper formatting
     def text_content
-      return '' unless content
+      return "" unless content
 
-      content.map { |item| item.respond_to?(:text_content) ? item.text_content : '' }.join("\n")
+      content.map do |item|
+        item.respond_to?(:text_content) ? item.text_content : ""
+      end.join("\n")
     end
 
-    # Override to_h to exclude empty attrs
-    def to_h
-      hash = super
-      hash['attrs'] ||= {}
-      hash['attrs']['bullet_style'] = bullet_style
-      hash
+    def bullet_style=(value)
+      @bullet_style = value
+      return if value.nil?
+
+      self.attrs ||= {}
+      attrs["bullet_style"] = value
+    end
+
+    def bullet_style
+      @bullet_style || attrs&.[]("bullet_style")
     end
   end
 end

data/lib/prosereflect/code_block.rb

@@ -1,27 +1,27 @@
 # frozen_string_literal: true
 
-require_relative 'node'
-
 module Prosereflect
   # CodeBlock class represents a code block in ProseMirror.
   class CodeBlock < Node
-    PM_TYPE = 'code_block'
+    PM_TYPE = "code_block"
 
-    attribute :type, :string, default: -> { send('const_get', 'PM_TYPE') }
+    attribute :type, :string, default: -> {
+      self.class.send(:const_get, "PM_TYPE")
+    }
     attribute :language, :string
     attribute :line_numbers, :boolean
     attribute :attrs, :hash
 
     key_value do
-      map 'type', to: :type, render_default: true
-      map 'attrs', to: :attrs
-      map 'content', to: :content
+      map "type", to: :type, render_default: true
+      map "attrs", to: :attrs
+      map "content", to: :content
     end
 
     def initialize(attributes = {})
       attributes[:attrs] ||= {
-        'content' => nil,
-        'language' => nil
+        "content" => nil,
+        "language" => nil,
       }
       super
     end
@@ -33,38 +33,38 @@ module Prosereflect
     def language=(value)
       @language = value
       self.attrs ||= {}
-      attrs['language'] = value
+      attrs["language"] = value
     end
 
     def language
-      @language || attrs&.[]('language')
+      @language || attrs&.[]("language")
     end
 
     def line_numbers=(value)
       @line_numbers = value
       self.attrs ||= {}
-      attrs['line_numbers'] = value
+      attrs["line_numbers"] = value
     end
 
     def line_numbers
-      @line_numbers || attrs&.[]('line_numbers') || false
+      @line_numbers || attrs&.[]("line_numbers") || false
     end
 
     def content=(value)
       @content = value
       self.attrs ||= {}
-      attrs['content'] = value
+      attrs["content"] = value
     end
 
     def content
-      @content || attrs&.[]('content')
+      @content || attrs&.[]("content")
     end
 
     attr_reader :highlight_lines_str
 
     def highlight_lines=(lines)
       @highlight_lines_str = if lines.is_a?(Array)
-                               lines.join(',')
+                               lines.join(",")
                              else
                                lines.to_s
                              end
@@ -73,7 +73,7 @@ module Prosereflect
     def highlight_lines
       return [] unless @highlight_lines_str
 
-      @highlight_lines_str.split(',').map(&:to_i)
+      @highlight_lines_str.split(",").map(&:to_i)
     end
 
     def text_content
@@ -82,12 +82,8 @@ module Prosereflect
 
     def to_h
       hash = super
-      hash['attrs'] = {
-        'content' => content,
-        'language' => language
-      }
-      hash['attrs']['line_numbers'] = line_numbers if line_numbers
-      hash.delete('content')
+      hash["attrs"] = { "language" => language }
+      hash["attrs"]["line_numbers"] = line_numbers if line_numbers
       hash
     end
 
@@ -96,7 +92,7 @@ module Prosereflect
       {
         language: language,
         line_numbers: line_numbers,
-        highlight_lines: highlight_lines
+        highlight_lines: highlight_lines,
       }.compact
     end
 
@@ -118,14 +114,14 @@ module Prosereflect
       return content if lines.empty?
 
       min_indent = lines.reject(&:empty?)
-                        .map { |line| line[/^\s*/].length }
-                        .min || 0
+        .map { |line| line[/^\s*/].length }
+        .min || 0
 
       normalized_lines = lines.map do |line|
         if line.empty?
           line
         else
-          line[min_indent..] || ''
+          line[min_indent..] || ""
         end
       end
 

data/lib/prosereflect/code_block_wrapper.rb

@@ -1,27 +1,26 @@
 # frozen_string_literal: true
 
-require_relative 'node'
-require_relative 'code_block'
-
 module Prosereflect
   # CodeBlockWrapper class represents a pre tag that wraps code blocks in ProseMirror.
   class CodeBlockWrapper < Node
-    PM_TYPE = 'code_block_wrapper'
+    PM_TYPE = "code_block_wrapper"
 
-    attribute :type, :string, default: -> { send('const_get', 'PM_TYPE') }
+    attribute :type, :string, default: -> {
+      self.class.send(:const_get, "PM_TYPE")
+    }
     attribute :line_numbers, :boolean
     attribute :attrs, :hash
 
     key_value do
-      map 'type', to: :type, render_default: true
-      map 'attrs', to: :attrs
-      map 'content', to: :content
+      map "type", to: :type, render_default: true
+      map "attrs", to: :attrs
+      map "content", to: :content
     end
 
     def initialize(attributes = {})
       attributes[:content] ||= []
       attributes[:attrs] = {
-        'line_numbers' => false
+        "line_numbers" => false,
       }
       super
     end
@@ -33,11 +32,11 @@ module Prosereflect
     def line_numbers=(value)
       @line_numbers = value
       self.attrs ||= {}
-      attrs['line_numbers'] = value
+      attrs["line_numbers"] = value
     end
 
     def line_numbers
-      @line_numbers || attrs&.[]('line_numbers') || false
+      @line_numbers || attrs&.[]("line_numbers") || false
     end
 
     def add_code_block(code = nil)
@@ -57,8 +56,8 @@ module Prosereflect
 
     def to_h
       hash = super
-      hash['attrs'] = {
-        'line_numbers' => line_numbers
+      hash["attrs"] = {
+        "line_numbers" => line_numbers,
       }
       hash
     end