lexxy-realtime 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ca9f7e8da5b292e73222ff67b6f49f6abe35825faf45af947157d4442fa37ce
+  data.tar.gz: a5aa12d0c2835df82d5eefa99e884b1920af507e824eb7ee3ee032d8b1c06a41
+SHA512:
+  metadata.gz: 2eb4bbdc5584615480b1b8cde54df071b1a38cce8c84cd6eaca8e14dbce7a57617f3f5c758d9b3c9dbc226a2c69c15d2f1a84ef69b5aa986824c7182498fb420
+  data.tar.gz: a9ec33bca8104051993e0d4a2fc6233afb459bf9e8a6cd63d72b1801f316244d5ef161d38e33d1ca7c325446f87d16622eb8bd7ce3cb20952eaf13d146d0f0ed

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JP Camara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+# lexxy-realtime (Rails gem)
+
+Collaborative [Lexxy](https://github.com/basecamp/lexxy) editing for
+Rails, backed by [yrby](https://github.com/jpcamara/yrby)'s Ruby
+implementation of Yjs.
+
+## Install
+
+Requires Ruby 3.4+, Rails 8.0.2+, and a working
+[Lexxy](https://github.com/basecamp/lexxy) installation (its gem and
+editor JavaScript). Import maps and bundlers (esbuild, Vite, webpack)
+both work.
+
+```ruby
+# Gemfile
+gem "lexxy-realtime"
+```
+
+```bash
+bin/rails generate lexxy_realtime:install
+bin/rails db:migrate
+```
+
+The generator creates `app/channels/document_channel.rb`, installs
+yrby's table migration, and adds the standard Action Cable files when
+they are missing. The `Y::Document` and `Y::DocumentUpdate` models come
+from `yrby-rails`.
+
+With a bundler, install the JavaScript package and import it next to
+your Lexxy import:
+
+```bash
+npm install lexxy-realtime   # yarn, bun, and pnpm also work
+```
+
+With import maps, there is no npm install; the generator pins assets
+this gem ships:
+
+```ruby
+# config/importmap.rb, added by the generator
+pin "lexical", to: "lexxy_realtime/lexical.js"
+pin "@37signals/lexxy", to: "lexxy_realtime/lexxy.js"
+pin "lexxy-realtime", to: "lexxy_realtime/lexxy-realtime.js"
+pin "@rails/activestorage", to: "activestorage.esm.js"
+```
+
+`lexical` is the one module the Lexxy and lexxy-realtime bundles share,
+so both ship with it external and it resolves through its own pin. The
+`@37signals/lexxy` pin must point at this gem's build: Lexxy's own
+asset bundles a second copy of `lexical`, and two copies break the
+collaboration binding, so remove any pin of Lexxy's asset. Keep
+`stylesheet_link_tag "lexxy"` for the editor's CSS. These assets are a
+stopgap until Lexxy ships import-map-ready builds itself.
+
+Either way, your entrypoint imports both:
+
+```js
+import "@37signals/lexxy"
+import "lexxy-realtime"
+```
+
+## Use
+
+```ruby
+class Post < ApplicationRecord
+  has_collaborative_rich_text :body   # a regular Action Text attribute
+end
+```
+
+```erb
+<%= form_with model: @post do |form| %>
+  <%= form.collaborative_rich_textarea :body %>
+<% end %>
+```
+
+Add your app's access check to `authorized?` in the generated channel,
+then open the page in two browsers and edit together. The record must be persisted
+(the document key derives from it). A record with an existing body works: the
+first collaborative open seeds the document from it.
+
+Encryption works the way Action Text's does:
+
+```ruby
+has_collaborative_rich_text :body, encrypted: true
+```
+
+The rendered body goes through `ActionText::EncryptedRichText`, and the
+collaborative document (CRDT state and update payloads) is stored through
+yrby's `Y::EncryptedDocument`. Both use Active Record encryption, so the
+app must configure encryption keys. Without Action Text, declare
+`encrypts` on the plain attribute yourself.
+
+Use it for new attributes. Existing plaintext rows need migration
+before you add `encrypted: true`: enable `support_unencrypted_data`,
+rewrite each document, update, and rich-text row through its encrypted
+class, then turn it back off. There is no built-in task for that yet.
+And if your channel came from an earlier pre-release checkout, update it
+to the current record-based storage first; a channel calling
+`Y::Document` directly stores encrypted attributes as plaintext.
+
+## How the body stays current
+
+The channel records each CRDT update, renders the full document with
+`Y::Lexxy`, and saves the HTML through the Action Text writer. This
+happens synchronously in `refresh_collaborative_rich_text`, so
+reads use the stored `post.body` value.
+
+If rendering fails, the update remains stored and the error is logged.
+The next successful update renders the full document again. Until then,
+`post.body` keeps its previous value.
+
+## Access control
+
+The form helper gives clients a signed GlobalID scoped to one record and
+field. `DocumentChannel` uses it to locate the record. Put the user
+access check in `authorized?` (for example,
+`record.editable_by?(current_user)`).
+
+## Configuration
+
+```ruby
+LexxyRealtime.identity = ->(view) { { name: view.current_user.handle, color: nil } }
+```
+
+By default, identity uses the first available `current_user` value from
+`name`, `username`, or `handle`, then falls back to `"Anonymous"`.
+
+Full documentation, the demo app, and the JavaScript package:
+[repository README](https://github.com/jpcamara/lexxy-realtime#readme).