yrby 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb0de1a9048f2aa942aad3bafed3269a029ed28ea178a72cb0f532e163cbb5f5
-  data.tar.gz: 6949735cd0edca033e78ef060333b91c40af2e3f900a79da46885d6630e6bc32
+  metadata.gz: 93704595e7dd617d4eccd0645a3dbc99bc798e11ec2591c86f47f0da08381d2c
+  data.tar.gz: 3f4fb67f5fc0368fe31a74cdae2104b9cea8bc44e349b398efc20f84fca7061a
 SHA512:
-  metadata.gz: 3f0a9aeea9e3efdd443f7da526eaf692226015a5a6be037527e1600b74cb2529e123fbcf0f03d91282ad4b60e96cfd5d81d51d149ec1f42b06f27664f4cf3ffb
-  data.tar.gz: 5532beea7978401cf18a2970eac4eefdc037c075bc6de2fb56b92978b3dc5e8b3c5759b9b6d9aabfb879ba92517e3792810ab14fabf9ef4461da30bfa2bd4c39
+  metadata.gz: fbe8957a8298efdb2991fa2de86a184e3395cb4315f7e467c2ee1dc1c37e750404468e9a2e71bf55967a44ca281424e4310fc4d985503171ca50a10bb3341e90
+  data.tar.gz: a29fd67645ef0b5312e34213eaf13c42e0eb8628a4e1da1d6af08ff6a68b77673f0f6e32c74f52da5797a3b802573ca78559e4a94a0c36da5b22331102a0ade6

data/CHANGELOG.md

@@ -4,7 +4,86 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims
 to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.0] - 2026-07-11
+
+### Added
+
+- **Custom render rules for `Y::Lexical` and `Y::ProseMirror`.** Both
+  renderers now take a block registering rules per node type —
+  `rules.node "callout", tag: "aside"` for markup-as-data, a Ruby block for
+  logic — plus `nodes:`/`marks:` keywords as the equivalent data form, to
+  render node types the pinned schemas don't know or to override how a
+  built-in renders.
+  Declarative rules (`tag`/`attrs`/`text`/`contains`, with templates mixing
+  literals and attribute references) render natively at full speed. Callback
+  rules run a Ruby block per node, receiving its type, attributes,
+  already-rendered children, and `child_types` (its element/block children by
+  type — the structural facts behind gallery counts and nested-list classes).
+  The block runs after the document read has finished, never while the doc is
+  locked, so it can safely read or write the same doc. Blocks are proven
+  sufficient for whole schemas: the gem's own editor schemas (`Y::Lexxy`,
+  `Y::Tiptap`) ship through this API, and the fixture tests hold their
+  output byte-identical to a live editor's. With no callback rules the
+  render path is unchanged, byte for byte. See "Custom nodes and marks" in
+  the README.
+- **`Y::Lexical#node_types` / `Y::ProseMirror#node_types` — schema
+  discovery.** Ask a real document which node types it holds and what they
+  look like: counts, attribute names as stored, child types, whether text
+  runs appear, and whether a builtin or one of your rules already handles
+  each ("handled" nil marks what still needs a rule). Editors store names
+  you'd never guess; this is how you find them.
+- `Y::RenderRules.escape_text` / `escape_attr` — the exact escaping the
+  native renderers use, for blocks that build markup from stored values
+  (ERB's `html_escape` also rewrites apostrophes, which breaks byte parity
+  with editor output).
+
+### Changed
+
+- **Lexical rendering is now two classes: `Y::Lexical` (core Lexical) and
+  `Y::Lexxy` (core plus the Lexxy schema as render rules).** Stock Lexical
+  has no canonical serializer, so the editor-specific class carries the
+  editor's name — `Y::Lexxy.new(doc).to_html` is the byte-parity call for
+  Lexxy/Rails apps, and `Y::Lexical` is the base any other Lexical editor
+  extends with its own rules. The
+  native side renders core structure — paragraphs, headings, quotes, code,
+  lists, tables, links, the full text-format model. Lexxy's own node types
+  (attachments, galleries, `early_escape_code`, `horizontal_divider`) and its
+  decorations of core nodes (the table figure wrapper, header-cell styling,
+  the nested-list-item class) are rules applied beneath the app's, on the
+  same extension API — the gem's Lexxy support is the API's first consumer.
+  Output is unchanged: the fixture tests still hold `to_html` byte-identical
+  to a live editor's serialized value, now through the extension path. An
+  unknown Lexical container also degrades better: its block children render
+  without an invented wrapper instead of being dropped.
+- **ProseMirror rendering gets the same split: `Y::ProseMirror` (core
+  ProseMirror) and `Y::Tiptap` (core plus Tiptap's extension nodes as render
+  rules).** `Y::Tiptap.new(doc).to_html` is the byte-parity call for Tiptap
+  apps. The native side renders prosemirror-schema-basic plus the
+  prosemirror-tables family; Tiptap's extension nodes — task lists, mentions,
+  the details family — are `Y::Tiptap::NODES` rules. Marks stay native in the
+  base class: mark rendering (nesting order, `textStyle` CSS, `code`
+  exclusivity) runs through text-run machinery node rules don't reach, so
+  `Y::ProseMirror` still renders Tiptap's full mark set and `rules.mark`
+  overrides individual marks. Output through `Y::Tiptap` is unchanged, held
+  byte-identical to a live editor's `getHTML()` by the fixture tests.
+
+## [0.5.0] - 2026-07-08
+
+### Added
+
+- **`Y::Lexical` — render Lexical/Lexxy documents to HTML.**
+  `Y::Lexical.new(doc).to_html` turns a Lexxy document into HTML on the server,
+  with no Node process or headless editor. The output is identical to the HTML
+  a `lexxy-editor` submits to Rails; the tests check it byte-for-byte against a
+  document captured from a real editor. It covers the whole Lexxy 0.9.x node
+  set: headings, every text format, links, bullet/numbered/check/nested lists,
+  quotes, code blocks, horizontal rules, tables with header cells, image galleries, and
+  ActionText attachments. Unknown nodes fall back to a plain paragraph, and a
+  root that isn't Lexical (a ProseMirror document, say) returns `nil`. This is
+  what `tiptap-php` does for ProseMirror JSON, applied to the Yjs structure.
+- `read_xml` now pulls text out of attachments too: a mention's text goes
+  inline, and an upload adds its caption, alt text, or filename. Before, both
+  were dropped.
 
 ## [0.4.0] - 2026-07-07
 

data/README.md

@@ -129,6 +129,27 @@ The rest of the dev setup, plus the demo, is in [CONTRIBUTING.md](CONTRIBUTING.m
   and the test/load suites.
 - [CHANGELOG.md](CHANGELOG.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
 
+## Editors
+
+yrby syncs opaque Yjs updates, so it works with any editor that has a Yjs
+binding. The demo app runs four, and CI drives each one in real Chrome:
+concurrent typing with every keystroke accounted for, remote cursors,
+local-only undo, and byte parity between the server-side renderers and the
+editor's own serializer. Each page is a working integration to copy from:
+
+| Editor | Yjs binding | Demo code |
+|---|---|---|
+| [Tiptap](https://tiptap.dev) (v2) | `@tiptap/extension-collaboration` | [`app.js`](examples/actioncable-demo/frontend/src/app.js) |
+| [Lexxy](https://github.com/basecamp/lexxy) (Lexical) | [`lexxy-realtime`](https://www.npmjs.com/package/lexxy-realtime) | [`lexxy.js`](examples/actioncable-demo/frontend/src/lexxy.js) |
+| [Rhino Editor](https://github.com/KonnorRogers/rhino-editor) (Tiptap 3) | `@tiptap/extension-collaboration` + `-caret` | [`rhino.js`](examples/actioncable-demo/frontend/src/rhino.js) |
+| [CodeMirror 6](https://codemirror.net) | `y-codemirror.next` | [`codemirror.js`](examples/actioncable-demo/frontend/src/codemirror.js) |
+
+The demo also syncs plain Yjs shapes with no editor at all — a whiteboard
+on a `Y.Map`, a kanban board on a `Y.Array`, a co-filled form — over the
+same channel. The demo README's "Using this in your own app" section has
+the integration recipe, and its `NoteMaterializer` shows how to render a
+document to ActionText server-side with `Y::Tiptap` or `Y::Lexxy`.
+
 ## Usage
 
 ### Doc (Low-Level Document Sync)
@@ -157,6 +178,17 @@ doc.handle_sync_message(data)     # => [msg_type, sync_type, response]; answers
                                   #    SyncStep2 (never serves pending structs)
 ```
 
+### Reading document contents
+
+Reconstruct a document server-side — search, exports, emails, SSR — with no
+Node process:
+
+```ruby
+doc.read_text("prosemirror")  # => plain text of a Y.Text root, or nil
+doc.read_xml("root")          # => text of an XML root, one block per line
+doc.read_map("state")         # => a Y.Map root as a JSON string; JSON.parse it
+```
+
 ### Pending structs and gap-free state
 
 If a doc applies an update whose causally-prior update is missing (a "gappy"
@@ -177,18 +209,24 @@ guarantees keep serving safe:
 
 ### Rendering to HTML
 
-`Y::ProseMirror` renders a ProseMirror or Tiptap document to HTML on the
-server, with no Node process or headless editor:
+Schema-pinned renderers turn a collaborative document into HTML on the
+server, with no Node process or headless editor. Each is an editor-specific
+class (byte-for-byte with that editor's own serializer) built on a core base
+any other editor extends with rules: `Y::Tiptap` on `Y::ProseMirror` for
+ProseMirror documents, and `Y::Lexxy` (the
+[Lexxy](https://github.com/basecamp/lexxy) editor) on `Y::Lexical`. Each
+returns `nil` for a root that belongs to the other schema.
+
+#### `Y::Tiptap` (and `Y::ProseMirror`, its base)
 
 ```ruby
-prosemirror = Y::ProseMirror.new(doc)
-prosemirror.to_html            # the "default" fragment (Tiptap's default root)
-prosemirror.to_html("content") # or another XML root
+tiptap = Y::Tiptap.new(doc)
+tiptap.to_html            # the "default" fragment (Tiptap's default root)
+tiptap.to_html("content") # or another XML root
 ```
 
 The output matches Tiptap's own `getHTML()`, checked byte-for-byte in the tests
-against a document captured from a real editor. So you can render, search, or
-email a collaborative document without running a browser. It follows
+against a document captured from a real editor. It follows
 [`tiptap-php`](https://github.com/ueberdosis/tiptap-php) and reads both name
 styles editors use — Tiptap's `bulletList`/`bold` and prosemirror-schema-basic's
 `bullet_list`/`strong`.
@@ -197,8 +235,212 @@ It covers paragraphs, headings, blockquotes, bullet/ordered/task lists, code
 blocks, links, images, mentions, details, hard breaks, horizontal rules,
 tables, text styles (color, font family), and every text mark. A table renders
 as semantic `<table><tbody>`, without the column-width styling Tiptap's editor
-view adds. A root that isn't ProseMirror — a Lexical document, say — returns
-`nil`.
+view adds.
+
+The support is layered like the Lexical side: `Y::ProseMirror` covers core
+ProseMirror natively — prosemirror-schema-basic plus the prosemirror-tables
+family — and Tiptap's extension nodes (task lists, mentions, the details
+family) are `Y::Tiptap`'s rule set (`Y::Tiptap::NODES`), built on the
+extension API below. Marks stay in the base: mark rendering (nesting order,
+`textStyle` CSS, `code` exclusivity) runs through native text-run machinery
+that node rules don't reach, so `Y::ProseMirror` renders Tiptap's mark set
+as-is and `rules.mark` overrides individual marks.
+
+#### `Y::Lexxy` (and `Y::Lexical`, its base)
+
+```ruby
+lexxy = Y::Lexxy.new(doc)
+lexxy.to_html            # the "root" fragment (Lexical's default root name)
+lexxy.to_html("notepad") # or another XML root
+```
+
+The HTML is identical to what a `lexxy-editor` submits to Rails (its `value`).
+The tests check this byte-for-byte against a document captured from a real
+editor. Stock Lexical has no canonical serializer — every editor configures
+its own — so the editor-specific class carries the editor's name, and
+`Y::Lexical` is the core-Lexical base: paragraphs, headings, quotes, code,
+lists, tables, links, and the full text-format model, for any other Lexical
+editor to extend with rules.
+
+It handles the whole Lexxy 0.9.x node set: paragraphs, headings, every text
+format and their combinations, links, the four list types and nesting,
+blockquotes, code blocks, tabs and soft breaks, horizontal rules, tables with
+header cells, image galleries, and ActionText attachments (uploads and
+mentions both emit `<action-text-attachment>` elements that ActionText can
+re-render).
+
+Internally that support is layered: `Y::Lexical` covers core Lexical
+structure natively, and everything Lexxy adds — its node types (attachments,
+galleries) and its decorations of core nodes (the table wrapper, header-cell
+styling, nested-list classes) — is `Y::Lexxy`'s rule set
+(`Y::Lexxy::NODES`), built on the extension API below. The gem's own Lexxy
+support is the API's first consumer: an app rule for one of those types
+simply replaces it.
+
+In both renderers an unknown node keeps its content — text and nested blocks
+fall back to readable markup rather than disappearing.
+
+#### Custom nodes and marks
+
+The built-in schemas are pinned to what Tiptap and Lexxy ship, but apps add
+their own node types. Both renderers take rules for them. A rule is checked
+before the built-in schema, so it can add a node type or replace how a
+built-in renders.
+
+Rules register in a block — one `rules.node` call per type. A declarative
+rule is markup as data, rendered natively:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.node "callout", tag: "aside",
+                        attrs: { "class" => ["callout callout--", :kind] },
+                        contains: :blocks
+end
+```
+
+`tag` names the element. `attrs` values are templates: a string is a literal,
+a symbol reads that attribute off the node, an array concatenates both kinds;
+an attribute that resolves empty is left out. `text` (same template form)
+emits literal text content. `contains` declares what lives inside the node — `:inline` (formatted text,
+the default), `:blocks` (child block nodes — a container), or `:none` (a
+leaf). `void: true` skips the closing tag.
+
+You don't have to guess any of those names or shapes. Editors store types
+and attributes under names you'd never predict (Rhino's strike mark is
+`rhino-strike`; Lexical prefixes its own props `__`), so ask a real
+document instead — make one in your editor using your custom node, then:
+
+```ruby
+Y::Tiptap.new(doc).node_types
+# => { "callout"   => { "count" => 2, "attrs" => ["kind"],
+#                       "children" => ["paragraph"], "text" => false,
+#                       "handled" => nil },
+#      "paragraph" => { ..., "handled" => "builtin" } }
+```
+
+`handled` nil marks the types that still need a rule; `attrs` are the stored
+names your templates and blocks will read; `children` plus `text` is how you
+pick `contains:` (child block types → `:blocks`; text → `:inline`).
+
+When markup-as-data isn't enough, give the node a block:
+
+```ruby
+lexical = Y::Lexical.new(doc) do |rules|
+  rules.node "video_embed" do |node|
+    src = ERB::Util.html_escape(node.attrs["__src"])
+    %(<video controls src="#{src}"></video>)
+  end
+end
+```
+
+The block gets the node's type, its stored attributes, `node.content` — the
+children, already rendered to HTML — and `node.child_types`, the node's
+element/block children by type, in document order. `child_types` answers the
+structural questions attributes can't: how many images a gallery holds, or
+whether a list item carries a nested list. Whatever the block returns is
+spliced into the output as-is: it's trusted HTML, so escape any values you
+interpolate. To set the content mode for a callback, give the node both —
+`rules.node "embed", contains: :blocks do |node| ... end`.
+
+Callbacks never run while the document is locked. The render finishes first
+(inside one read transaction, GVL released), then the blocks run and their
+output is spliced in — so a callback can safely read or even write the same
+doc. With no callback rules, `to_html` skips the splicing entirely.
+
+Blocks are the escape hatch for everything the declarative form can't say,
+and they're proven sufficient: `Y::Lexxy` and `Y::Tiptap` are themselves
+built on this API (`lib/y/lexxy.rb`, `lib/y/tiptap.rb`) — simple nodes as
+declarative hashes, everything with logic as plain methods mapped by node
+type (a `Method` responds to `call` like any lambda) — and the fixture tests
+hold their output byte-identical to a live editor's.
+
+The ProseMirror side also takes custom marks:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.mark "comment", tag: "span", attrs: { "data-comment-id" => :id }
+end
+```
+
+Symbol refs resolve against the mark's own attributes. A custom mark wraps
+outside every built-in mark; several on one run nest alphabetically. A rule
+for a built-in mark name (`"bold"`) replaces its built-in tag.
+
+##### Worked examples
+
+A video-embed node from an app's Tiptap extension — a type the pinned schema
+has never heard of:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.node "videoEmbed" do |node|
+    src   = ERB::Util.html_escape(node.attrs["src"])
+    title = ERB::Util.html_escape(node.attrs["title"] || "Video")
+    %(<figure class="video"><iframe src="#{src}" title="#{title}" allowfullscreen></iframe></figure>)
+  end
+end
+```
+
+Resolving mentions against the database. Blocks run after the document read
+has finished, so hitting ActiveRecord (or the doc itself) inside one is safe:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.node "mention" do |node|
+    user = User.find_by(id: node.attrs["id"])
+    next "<span>@unknown</span>" unless user
+
+    %(<a class="mention" href="/users/#{user.id}">@#{ERB::Util.html_escape(user.handle)}</a>)
+  end
+end
+```
+
+Overriding a shipped rule — rendering Lexxy uploads as real image markup
+instead of the `<action-text-attachment>` elements ActionText re-renders:
+
+```ruby
+lexxy = Y::Lexxy.new(doc) do |rules|
+  rules.node "action_text_attachment" do |node|
+    src     = ERB::Util.html_escape(node.attrs["src"])
+    alt     = ERB::Util.html_escape(node.attrs["altText"].to_s)
+    caption = node.attrs["caption"].to_s
+    html = %(<img src="#{src}" alt="#{alt}" loading="lazy">)
+    html += "<figcaption>#{ERB::Util.html_escape(caption)}</figcaption>" unless caption.empty?
+    "<figure>#{html}</figure>"
+  end
+end
+```
+
+Markup that depends on structure — `node.child_types` lists the node's
+element/block children in document order, so a layout container can size
+itself by its column count while the columns themselves stay declarative:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.node "columns", contains: :blocks do |node|
+    %(<div class="columns columns--#{node.child_types.length}">#{node.content}</div>)
+  end
+  rules.node "column", tag: "div", attrs: { "class" => "column" }, contains: :blocks
+end
+```
+
+Content-aware overrides — dropping the empty paragraphs an editor keeps
+around the cursor, since `node.content` arrives already rendered:
+
+```ruby
+lexical = Y::Lexical.new(doc) do |rules|
+  rules.node "paragraph" do |node|
+    node.content.empty? ? "" : "<p>#{node.content}</p>"
+  end
+end
+```
+
+For a larger reference, the gem's own editor schemas ship this way — see
+`Y::Lexxy::NODES` in `lib/y/lexxy.rb` (declarative hashes for the simple
+nodes, a plain method per node that needs logic — galleries, list items,
+header cells, both attachment types — mapped with `method(:name)`) and
+`Y::Tiptap::NODES` in `lib/y/tiptap.rb` (task lists, mentions, the details
+family).
 
 ### Protocol codec (module functions)