lexxy-realtime 0.4.0

data/lib/generators/lexxy_realtime/install/USAGE

@@ -0,0 +1,15 @@
+Description:
+    Installs the channel and database tables required for collaborative
+    Lexxy editing. The channel locates records by signed GlobalID and
+    saves rendered updates to Action Text.
+
+Example:
+    bin/rails generate lexxy_realtime:install
+
+    This will create:
+        app/channels/document_channel.rb
+        app/channels/application_cable/{connection,channel}.rb  (if missing)
+        db/migrate/XXXXXXXX_create_y_tables.rb
+    The models ship in the gems (Y::Document, Y::DocumentUpdate).
+    The generator will remind you to add `import "lexxy-realtime"` to
+    your JavaScript entrypoint.

data/lib/generators/lexxy_realtime/install/install_generator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "generators/yrby/tables/tables_generator"
+
+module LexxyRealtime
+  module Generators
+    # Installs the document channel, the storage migration (via yrby's
+    # generator), and the Action Cable boilerplate when missing.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      # rails new --skip-action-cable leaves nothing for the channel to
+      # inherit from.
+      def check_action_cable
+        return if defined?(ActionCable)
+
+        say "Action Cable is not loaded (rails new --skip-action-cable?). " \
+            'Add `require "action_cable/engine"` to config/application.rb, ' \
+            "create config/cable.yml, and re-run this generator.", :red
+        raise Thor::Error, "lexxy_realtime:install requires Action Cable"
+      end
+
+      def create_application_cable
+        %w[connection channel].each do |file|
+          destination = "app/channels/application_cable/#{file}.rb"
+          next if File.exist?(File.join(destination_root, destination))
+
+          template "application_cable_#{file}.rb", destination
+        end
+      end
+
+      def create_channel
+        template "document_channel.rb", "app/channels/document_channel.rb"
+      end
+
+      # yrby owns the models and their migration.
+      def create_tables
+        invoke "yrby:tables"
+      end
+
+      # Import-map apps get pins to the assets this gem ships. The Lexxy
+      # pin must point at this gem's build (Lexxy's own asset bundles a
+      # second copy of lexical, which breaks collaboration), so an
+      # existing @37signals/lexxy pin is left for the app to resolve.
+      def add_importmap_pins
+        return unless File.exist?(File.join(destination_root, "config/importmap.rb"))
+        return if File.read(File.join(destination_root, "config/importmap.rb")).include?("lexxy_realtime/")
+
+        append_to_file "config/importmap.rb", <<~RUBY
+
+          # lexxy-realtime. lexical is shared between the Lexxy and
+          # lexxy-realtime bundles; @37signals/lexxy must point at the
+          # lexxy_realtime build, not Lexxy's own asset.
+          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"
+        RUBY
+      end
+
+      def show_next_steps
+        say <<~NEXT
+
+          lexxy-realtime is installed. Lexxy itself (the gem and its editor
+          JS) must already be installed and working. Next steps:
+
+            1. bin/rails db:migrate
+            2. Wire up the JavaScript. With import maps, the generator
+               added pins; import "@37signals/lexxy" and "lexxy-realtime"
+               from your entrypoint, and remove any pin for Lexxy's own
+               asset. With a bundler, install the lexxy-realtime npm
+               package and import it.
+            3. Declare `has_collaborative_rich_text :body` on a model and
+               render it with `<%= form.collaborative_rich_textarea :body %>`.
+            4. Update `authorized?` in app/channels/document_channel.rb
+               to check the current user.
+
+          Optional: set cursor names with `LexxyRealtime.identity`.
+        NEXT
+      end
+    end
+  end
+end

data/lib/generators/lexxy_realtime/install/templates/application_cable_channel.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end

data/lib/generators/lexxy_realtime/install/templates/application_cable_connection.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    # Expose the current user to DocumentChannel#authorized?:
+    #
+    #   identified_by :current_user
+    #
+    #   def connect
+    #     self.current_user = User.find_by(id: cookies.signed[:user_id]) || reject_unauthorized_connection
+    #   end
+  end
+end

data/lib/generators/lexxy_realtime/install/templates/document_channel.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Syncs clients with the record's collaborative document. After storing
+# each update, the Action Text attribute is refreshed from the full
+# document.
+class DocumentChannel < ApplicationCable::Channel
+  include Y::ActionCable
+
+  # Storage routes through the record's association, so an encrypted
+  # attribute reads and writes through Y::EncryptedDocument.
+  on_load { |_key| record.find_or_create_collaborative_document(field).load_state }
+  on_change do |key, update|
+    record.find_or_create_collaborative_document(field).append(update)
+    # Log render failures. The stored document renders again after the
+    # next update. Raising would make the client resend an update the
+    # server already has.
+    begin
+      record.refresh_collaborative_rich_text(field)
+    rescue StandardError => e
+      Rails.logger.error("lexxy-realtime render failed for #{key}: #{e.class}: #{e.message}")
+    end
+  end
+
+  def subscribed
+    reject and return unless record&.collaborative_rich_text?(field)
+    reject and return unless authorized?
+
+    sync_subscribed(record.find_or_create_collaborative_document(field).key)
+  end
+
+  def receive(data)
+    return unless record
+
+    sync_receive(data, record.find_or_create_collaborative_document(field).key)
+  end
+
+  private
+
+  # Check whether the current user may edit this record, e.g.
+  # record.editable_by?(current_user) with identified_by :current_user
+  # on the connection. Nothing connects until this returns true.
+  def authorized?
+    false
+  end
+
+  # Invalid, stale, or field-mismatched tokens return nil and are
+  # rejected by subscribed.
+  def record
+    @record ||= GlobalID::Locator.locate_signed(params[:sgid], for: LexxyRealtime.sgid_purpose(field))
+  rescue ActiveRecord::RecordNotFound
+    nil
+  end
+
+  def field
+    params[:field].to_s
+  end
+end

data/lib/lexxy-realtime.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Bundler requires by gem name; the code lives under the underscored path.
+require "lexxy_realtime"

data/lib/lexxy_realtime/collaborative.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module LexxyRealtime
+  # Adds Y::Document-backed collaboration to an attribute. When Action
+  # Text is available, it declares the corresponding +has_rich_text+
+  # association.
+  module Collaborative
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def has_collaborative_rich_text(name, **options) # rubocop:disable Naming/PredicatePrefix
+        include Model unless include?(Model)
+        has_rich_text(name, **options) if respond_to?(:has_rich_text)
+        self.collaborative_rich_text_names = (collaborative_rich_text_names + [name.to_sym]).freeze
+
+        # encrypted: true encrypts both halves: has_rich_text gets the
+        # option (an encrypted body), and the document stores CRDT state
+        # through Y::EncryptedDocument. Without Action Text, declare
+        # +encrypts+ on the plain attribute yourself.
+        document_class = options[:encrypted] ? "Y::EncryptedDocument" : "Y::Document"
+        has_one :"collaborative_document_#{name}", -> { where(name: name) },
+                class_name: document_class, as: :record, inverse_of: :record, dependent: :destroy
+      end
+    end
+
+    # The instance API, present only on models that declared an attribute.
+    module Model
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :collaborative_rich_text_names, instance_writer: false, default: [].freeze
+      end
+
+      def collaborative_rich_text?(name) = collaborative_rich_text_names.include?(name.to_sym)
+
+      # The document, if collaboration has started (nil until the first join).
+      def collaborative_document(name) = public_send("collaborative_document_#{name}")
+
+      # Creates the document on first use. The association supplies the
+      # class, so an encrypted attribute gets a Y::EncryptedDocument.
+      def find_or_create_collaborative_document(name)
+        collaborative_document(name) || begin
+          association(:"collaborative_document_#{name}").klass.for(self, name)
+          public_send("reload_collaborative_document_#{name}")
+        end
+      end
+
+      # Reloads and renders the document while holding the record lock,
+      # then saves the HTML through the attribute writer. Returns false
+      # when the document has no state.
+      def refresh_collaborative_rich_text(name)
+        ensure_collaborative!(name)
+
+        document = collaborative_document(name)
+        return false unless document
+
+        with_lock do
+          strict_loading!(false) if strict_loading? # the writer lazily loads the rich-text row
+          state = document.reload.load_state
+          break false if state.nil?
+
+          doc = Y::Doc.new
+          doc.apply_update(state)
+          html = Y::Lexxy.new(doc).to_html
+          break false if html.nil?
+
+          public_send("#{name}=", html)
+          save!(validate: false) # collaboration updates should not run unrelated model validations
+          true
+        end
+      end
+
+      private
+
+      def ensure_collaborative!(name)
+        return if collaborative_rich_text?(name)
+
+        raise ArgumentError, "#{name.inspect} is not collaborative on #{self.class.name}"
+      end
+    end
+  end
+end

data/lib/lexxy_realtime/engine.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require "action_dispatch" # Engine::Configuration references it at subclass definition
+
+# Require the engine dependencies explicitly so their initializers run
+# during boot.
+require "lexxy"
+require "y"
+require "yrby-rails" # the sync concern, Y::Document storage, and yrby's engine
+
+module LexxyRealtime
+  class Engine < ::Rails::Engine
+    initializer "lexxy_realtime.active_record" do
+      ActiveSupport.on_load(:active_record) { include LexxyRealtime::Collaborative }
+    end
+
+    initializer "lexxy_realtime.form_builder" do |app|
+      app.config.to_prepare { ActionView::Helpers::FormBuilder.prepend(LexxyRealtime::FormBuilder) }
+    end
+
+    # The import-map assets under app/assets/javascript need no
+    # initializer: Rails adds every app/assets subdirectory of an engine
+    # to the asset paths itself.
+  end
+end

data/lib/lexxy_realtime/form_builder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module LexxyRealtime
+  # Renders a Lexxy editor with collaboration configured for the record
+  # and field. LexxyRealtime.identity supplies the cursor name and color.
+  module FormBuilder
+    def collaborative_rich_textarea(method, name: nil, color: nil, **options)
+      record = object
+      unless record.respond_to?(:collaborative_rich_text?) && record.collaborative_rich_text?(method)
+        raise ArgumentError,
+              "#{record.class.name}##{method} is not collaborative (declare has_collaborative_rich_text :#{method})"
+      end
+      raise ArgumentError, "#{record.class.name} must be persisted to collaborate on it" unless record.persisted?
+
+      identity = LexxyRealtime.identity.call(@template)
+      collaborator = name || identity[:name]
+      public_send(lexxy_editor_method, method, options) do
+        # The client-side Yjs binding key, shared by peers of this
+        # attribute. The server never sees it.
+        @template.content_tag("lexxy-collaboration", "",
+                              "doc-id" => "#{record.model_name.param_key}-#{record.id}-#{method}",
+                              "name" => collaborator,
+                              "color" => color || identity[:color] || LexxyRealtime.collaborator_color(collaborator),
+                              "channel-name" => LexxyRealtime::CHANNEL_NAME,
+                              "channel-params" => { sgid: record.to_sgid(for: LexxyRealtime.sgid_purpose(method)).to_s,
+                                                    field: method }.to_json)
+      end
+    end
+
+    alias collaborative_rich_text_area collaborative_rich_textarea
+
+    private
+
+    # Lexxy's explicit helper exists on Rails 8.0/8.1. On the
+    # ActionText::Editor adapter path in newer Rails, the standard
+    # rich_text_area renders Lexxy and accepts the block.
+    def lexxy_editor_method
+      respond_to?(:lexxy_rich_textarea) ? :lexxy_rich_textarea : :rich_text_area
+    end
+  end
+end

data/lib/lexxy_realtime/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LexxyRealtime
+  VERSION = "0.4.0"
+end

data/lib/lexxy_realtime.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "lexxy_realtime/version"
+require "lexxy_realtime/collaborative"
+require "lexxy_realtime/form_builder"
+require "lexxy_realtime/engine"
+
+# Rails integration for collaborative Lexxy editing with yrby.
+module LexxyRealtime
+  # Signed ids from the form helper carry this purpose scoped per field
+  # (sgid_purpose), so a token minted elsewhere can't join a document.
+  SGID_PURPOSE = :lexxy_realtime
+
+  # The channel the installer generates and the form helper points elements at.
+  CHANNEL_NAME = "DocumentChannel"
+
+  class << self
+    def sgid_purpose(field) = "#{SGID_PURPOSE}/#{field}"
+
+    # Cursor identity, called with the view context; returns { name:, color: }
+    # (a nil color gets a stable one derived from the name).
+    attr_writer :identity
+
+    def identity
+      @identity ||= lambda do |view|
+        user = view.respond_to?(:current_user) ? view.current_user : nil
+        # Use Anonymous when no display name is available.
+        name = user && %i[name username handle].lazy.filter_map { |a| user.try(a).presence }.first
+        { name: name || "Anonymous", color: nil }
+      end
+    end
+
+    # A stable, readable cursor color per collaborator name.
+    def collaborator_color(name)
+      "hsl(#{name.to_s.each_byte.reduce(0) { |acc, b| ((acc * 31) + b) % 360 }}, 70%, 45%)"
+    end
+  end
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: lexxy-realtime
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- JP Camara
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lexxy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.2
+- !ruby/object:Gem::Dependency
+  name: yrby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: yrby-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+description: Adds collaborative Lexxy editing to Rails applications using yrby. Includes
+  the model, form, channel, generator, and Action Text integration.
+email:
+- jp@jpcamara.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/assets/javascript/lexxy_realtime/lexical.js
+- app/assets/javascript/lexxy_realtime/lexical.js.map
+- app/assets/javascript/lexxy_realtime/lexical.min.js
+- app/assets/javascript/lexxy_realtime/lexxy-realtime.js
+- app/assets/javascript/lexxy_realtime/lexxy-realtime.js.map
+- app/assets/javascript/lexxy_realtime/lexxy-realtime.min.js
+- app/assets/javascript/lexxy_realtime/lexxy.js
+- app/assets/javascript/lexxy_realtime/lexxy.js.map
+- app/assets/javascript/lexxy_realtime/lexxy.min.js
+- lib/generators/lexxy_realtime/install/USAGE
+- lib/generators/lexxy_realtime/install/install_generator.rb
+- lib/generators/lexxy_realtime/install/templates/application_cable_channel.rb
+- lib/generators/lexxy_realtime/install/templates/application_cable_connection.rb
+- lib/generators/lexxy_realtime/install/templates/document_channel.rb
+- lib/lexxy-realtime.rb
+- lib/lexxy_realtime.rb
+- lib/lexxy_realtime/collaborative.rb
+- lib/lexxy_realtime/engine.rb
+- lib/lexxy_realtime/form_builder.rb
+- lib/lexxy_realtime/version.rb
+homepage: https://github.com/jpcamara/lexxy-realtime
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jpcamara/lexxy-realtime
+  source_code_uri: https://github.com/jpcamara/lexxy-realtime
+  changelog_uri: https://github.com/jpcamara/lexxy-realtime/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Collaborative editing for Lexxy in Rails
+test_files: []