yrby-rails 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 397e3f48e611d521d0afa26ddca292826276406b1fd04fb2bcfd09858a73081d
-  data.tar.gz: 51e88f6856f8a2859d18823e87ff2d5cd901e678e8b7a618ff7b2b0308d80c1d
+  metadata.gz: 56e31c8cc1697d3894702fdfff977817fe1c22bb95318718dd3b0940171ed74f
+  data.tar.gz: 2a3a49d17af5c0d690ab98ca0c3bf6f41f7c79d0a9b6041f3dd49b98f0829e84
 SHA512:
-  metadata.gz: 3299b4149a6dea79105be6bf69e643c8079029ac751bb50f68ce4b8d49ce570541b184f5b601215214d92b7848694a8b9a9a685eaf593f885378cbc8454e0a18
-  data.tar.gz: 4490087a7702972c2e447abcb2f4afff938d72e77704eb7cfc04d5a5272bc6e5248d22a883b193b3840db0aa5c3e602e6a0c50b57fb1d3169839e7530a764ff4
+  metadata.gz: 148304e573708e6ace7234f5de8ecde4020fa8139f4daf8284598b6a6c79f478791c342dc7b70ab91e4d65e9bbf11eb4dc88a82ea364c027d44714337228a9a7
+  data.tar.gz: 9b929e7b58b7524052bb18026aee2ec7a90d82b22fd8d0eb3b61275d4c912da416a3a442121a516643da8621984ff06e843f3405ad74eb64766e14005c00893b

data/CHANGELOG-rails.md

@@ -7,6 +7,75 @@ this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-11-09
+
+Requires yrby 0.9.0 or later.
+
+### Security
+
+- `Y::ActionCable::Sync`'s methods and `Y::DocumentChannel`'s
+  `authorized_document_key` accessors are private. Action Cable treats a
+  channel's public methods as actions a client can call, so a client could call
+  `sync_subscribed` directly and skip the channel's own `subscribed` and
+  `receive`. Channels that call these from `subscribed` and `receive` keep
+  working. Code that calls them on a channel from outside, such as a test, now
+  needs `send`.
+
+### Added
+
+- `bin/rails generate yrby:install` pins `yrby-client`, `yrby-client/element`,
+  `yjs`, and `@rails/actioncable` when the app has `config/importmap.rb`. The
+  gem ships `yrby/yrby-client.js` and `yrby/yjs.js` for those pins, so an
+  import-map app needs no npm packages. Each shared module has one pin, so the
+  page and its editor binding load one copy of yjs. Pins the app already has
+  are left alone.
+- `has_collaborative_document :body, channel: "PostDocumentChannel"` names
+  an app's own `Y::DocumentChannel` subclass for an attribute.
+  `collaborative_document(:body).channel` returns it, so
+  `collaborative_document_tag` and Ruby clients subscribe there without
+  passing `channel:` each time.
+
+## [0.8.0] - 2026-11-03
+
+Requires yrby 0.9.0 or later.
+
+### Experimental
+
+These are new, and they may change in a minor release. See
+[docs/experimental.md](docs/experimental.md).
+
+- `collaborative_document(:body).edit { |doc| ... }` edits a record's
+  document from Ruby. It records the change in the document's rows, encrypted
+  ones included, and broadcasts it to open editors.
+  `Y::ActionCable.broadcast(key, update)` sends an already recorded update.
+
+### Added
+
+- `collaborative_document(name)` answers `grant(expires_in:)` and `channel`:
+  the grant a page or client subscribes with, and the channel that accepts
+  it. A gem with its own grants and channel, such as lexxy-realtime, returns
+  its own document with both.
+
+### Changed
+
+- `collaborative_document_tag` renders the document's grant and channel, so
+  it works for a gem that returns its own document. `channel:` still
+  overrides the channel.
+
+### Deprecated
+
+- `collaborative_sgid(name, expires_in:)`. Use
+  `collaborative_document(name).grant(expires_in:)`. It logs through
+  `Y.deprecator`, which the engine adds to `Rails.application.deprecators`,
+  and goes away in yrby-rails 0.9.
+
+### Fixed
+
+- The channel relays a client's SyncStep2 to peers as a plain update.
+  Relayed as is, a peer that was still joining could take it for the answer
+  to its own handshake and report itself loaded before it had the server's
+  state.
+
 ## [0.7.0] - 2026-10-01
 
 ### Added

data/README.md

@@ -76,15 +76,21 @@ doc = post.collaborative_document(:body).y_doc
 doc.read_text("content")  # or Y::Lexxy.new(doc).to_html for rich text
 ```
 
-Install the gem and the npm package:
+Install the gem and run its generator:
 
 ```
-gem install yrby-rails # depends on yrby
-npm install yrby-client yjs y-protocols @rails/actioncable
-
+bundle add yrby-rails # depends on yrby
 bin/rails generate yrby:install && bin/rails db:migrate
 ```
 
+In an app that uses import maps, the generator pins `yrby-client`, `yjs`, and
+`@rails/actioncable` to JavaScript the gem ships. With a bundler, install the
+npm packages instead:
+
+```
+npm install yrby-client yjs y-protocols @rails/actioncable
+```
+
 ## Contents
 
 - [Scope](#scope)
@@ -101,6 +107,7 @@ bin/rails generate yrby:install && bin/rails db:migrate
   - [Rendering to HTML](#rendering-to-html)
   - [Protocol codec (module functions)](#protocol-codec-module-functions)
   - [ActionCable Integration](#actioncable-integration)
+- [Experimental: writing from Ruby, and collaborators](#experimental-writing-from-ruby-and-collaborators)
 - [Thread Safety](#thread-safety)
   - [Parallelism (GVL release)](#parallelism-gvl-release)
 - [Message Type Constants](#message-type-constants)
@@ -117,7 +124,9 @@ primitives. By default the Ruby side treats a document as opaque CRDT state. It
 applies updates, answers sync handshakes, and records deltas without reading
 the contents, and the browser editor decides what shape the document has. When
 you do need to look inside, `Doc#read_text` and `Doc#read_map` rebuild it in
-Ruby.
+Ruby, and live handles (`Doc#get_map`, `get_array`, `get_text`,
+`get_xml_text`) write to it. The handles are
+[experimental](docs/experimental.md).
 
 ## Durability and delivery
 
@@ -338,12 +347,12 @@ every editor configures its own. `Y::Lexical` is the core Lexical base
 (paragraphs, headings, quotes, code, lists, tables, links, and the full
 text-format model), and other Lexical editors extend it with rules.
 
-It handles every node in the Lexxy 0.9.x set: paragraphs, headings, every text
-format and their combinations, links, the four list types with nesting,
-blockquotes, code blocks, tabs and soft breaks, horizontal rules, tables with
-header cells, image galleries, and ActionText attachments. Uploads and mentions
-both render as `<action-text-attachment>` elements, which ActionText can
-re-render.
+It handles every node in Lexxy 1.0, which has the same set as 0.9.x:
+paragraphs, headings, every text format and their combinations, links, the
+four list types with nesting, blockquotes, code blocks, tabs and soft breaks,
+horizontal rules, tables with header cells, image galleries, and ActionText
+attachments. Uploads and mentions both render as `<action-text-attachment>`
+elements, which ActionText can re-render.
 
 The Lexical support has the same two layers. `Y::Lexical` handles core Lexical
 structure natively, and everything Lexxy adds is in `Y::Lexxy`'s rule set,
@@ -401,6 +410,13 @@ attribute names your templates and blocks will read, and `children` and `text`
 tell you which `contains:` to pick. Child block types mean `:blocks`, and text
 means `:inline`.
 
+`unknown_types` lists the types whose `handled` is nil. `to_html` still
+renders them as well as it can. An unknown container or inline wrapper renders
+its children without its own markup, so its text stays. A node that keeps its
+content only in its attributes renders nothing. Either way, the node's markup is
+missing from the HTML, and nothing raises. When you add editor nodes, add a test
+that renders a real document and asserts `unknown_types` is empty.
+
 When a declarative rule can't express the markup, give the node a block:
 
 ```ruby
@@ -654,6 +670,16 @@ the `authorize_document` block with the record and the attribute name, or to
 accept any valid grant when there's no block. A subclass can override
 `authorized?` directly and read the located record from `record`.
 
+A page subscribes to the channel its document names, `Y::DocumentChannel`
+unless the model says otherwise. Name a subclass where you declare the
+attribute, and the tag, a Ruby client, and a collaborator all use it:
+
+```ruby
+class Post < ApplicationRecord
+  has_collaborative_document :body, channel: "PostDocumentChannel"
+end
+```
+
 ### Grant lifetime and refresh
 
 A grant lasts as long as GlobalID's signed-id default, which is one month under
@@ -673,7 +699,7 @@ gets blocked at the next reconnect. To avoid that, pair `expires_in:` with
 # app/controllers/posts_controller.rb
 def grant
   @post = current_user.posts.find(params[:id])   # your own authorization, again
-  render json: { grant: @post.collaborative_sgid(:body, expires_in: 10.minutes) }
+  render json: { grant: @post.collaborative_document(:body).grant(expires_in: 10.minutes) }
 end
 ```
 
@@ -737,7 +763,7 @@ up the record from it, so the page decides which document the client gets.
 
 ```erb
 <%# the view picks the document and signs it %>
-<%= tag.div data: { grant: post.collaborative_sgid(:body) } %>
+<%= tag.div data: { grant: post.collaborative_document(:body).grant } %>
 ```
 
 ```ruby
@@ -1067,6 +1093,24 @@ The browser clients manage presence (cursors, selections). The server doesn't
 set or hold presence state, and it relays awareness frames without reading
 them. See `yrby-client` for the client-side awareness API.
 
+## Experimental: writing from Ruby, and collaborators
+
+These APIs are new. They may change in any minor release, and they aren't
+covered by yrby's usual compatibility promise.
+[docs/experimental.md](docs/experimental.md) documents them:
+
+- Live `Y::Map`, `Y::Array`, and `Y::Text` handles that write to a document
+- Writing Lexical rich text from Ruby, with `Y::Lexical` and `Y::Lexxy`
+- Anchors: a block's identity as a value
+- Streaming into a document with `Doc#edit`
+- Editing a record's document from Ruby
+- From the `yrby-agent` gem: joining a document from a Ruby process with
+  `Y::ActionCable::Client`, collaborators with `Y::Collaborator`, and agents
+  with `Y::Agent`
+
+`require "y/action_cable/client"`, `require "y/collaborator"`, and
+`require "y/agent"` print a warning in Ruby's `:experimental` category. `Warning[:experimental] = false` turns it off.
+
 ## Thread Safety
 
 You can share a `Doc` across Ruby threads. Puma workers, ActionCable connection