prosereflect 0.2.0 → 0.3.0

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

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/blockquote.rb

@@ -74,6 +74,15 @@ module Prosereflect
       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)
       paragraph = Paragraph.new
       paragraph.add_text(text)

data/lib/prosereflect/bullet_list.rb

@@ -19,22 +19,24 @@ module Prosereflect
 
     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)
@@ -73,12 +75,16 @@ module Prosereflect
       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

@@ -82,12 +82,8 @@ module Prosereflect
 
     def to_h
       hash = super
-      hash["attrs"] = {
-        "content" => content,
-        "language" => language,
-      }
+      hash["attrs"] = { "language" => language }
       hash["attrs"]["line_numbers"] = line_numbers if line_numbers
-      hash.delete("content")
       hash
     end