actiontext 7.1.5.2 → 8.1.2.1

data/lib/action_text/attachment.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/core_ext/object/try"
 
 module ActionText
-  # = Action Text \Attachment
+  # # Action Text Attachment
   #
   # Attachments serialize attachables to HTML or plain text.
   #
-  #   class Person < ApplicationRecord
-  #     include ActionText::Attachable
-  #   end
+  #     class Person < ApplicationRecord
+  #       include ActionText::Attachable
+  #     end
   #
-  #   attachable = Person.create! name: "Javan"
-  #   attachment = ActionText::Attachment.from_attachable(attachable)
-  #   attachment.to_html # => "<action-text-attachment sgid=\"BAh7CEk..."
+  #     attachable = Person.create! name: "Javan"
+  #     attachment = ActionText::Attachment.from_attachable(attachable)
+  #     attachment.to_html # => "<action-text-attachment sgid=\"BAh7CEk..."
   class Attachment
     include Attachments::TrixConversion, Attachments::Minification, Attachments::Caching
 
@@ -82,29 +84,29 @@ module ActionText
 
     # Converts the attachment to plain text.
     #
-    #   attachable = ActiveStorage::Blob.find_by filename: "racecar.jpg"
-    #   attachment = ActionText::Attachment.from_attachable(attachable)
-    #   attachment.to_plain_text # => "[racecar.jpg]"
+    #     attachable = ActiveStorage::Blob.find_by filename: "racecar.jpg"
+    #     attachment = ActionText::Attachment.from_attachable(attachable)
+    #     attachment.to_plain_text # => "[racecar.jpg]"
     #
-    # Use the +caption+ when set:
+    # Use the `caption` when set:
     #
-    #   attachment = ActionText::Attachment.from_attachable(attachable, caption: "Vroom vroom")
-    #   attachment.to_plain_text # => "[Vroom vroom]"
+    #     attachment = ActionText::Attachment.from_attachable(attachable, caption: "Vroom vroom")
+    #     attachment.to_plain_text # => "[Vroom vroom]"
     #
     # The presentation can be overridden by implementing the
-    # +attachable_plain_text_representation+ method:
+    # `attachable_plain_text_representation` method:
     #
-    #   class Person < ApplicationRecord
-    #     include ActionText::Attachable
+    #     class Person < ApplicationRecord
+    #       include ActionText::Attachable
     #
-    #     def attachable_plain_text_representation
-    #       "[#{name}]"
+    #       def attachable_plain_text_representation
+    #         "[#{name}]"
+    #       end
     #     end
-    #   end
     #
-    #   attachable = Person.create! name: "Javan"
-    #   attachment = ActionText::Attachment.from_attachable(attachable)
-    #   attachment.to_plain_text # => "[Javan]"
+    #     attachable = Person.create! name: "Javan"
+    #     attachment = ActionText::Attachment.from_attachable(attachable)
+    #     attachment.to_plain_text # => "[Javan]"
     def to_plain_text
       if respond_to?(:attachable_plain_text_representation)
         attachable_plain_text_representation(caption)
@@ -115,9 +117,9 @@ module ActionText
 
     # Converts the attachment to HTML.
     #
-    #   attachable = Person.create! name: "Javan"
-    #   attachment = ActionText::Attachment.from_attachable(attachable)
-    #   attachment.to_html # => "<action-text-attachment sgid=\"BAh7CEk...
+    #     attachable = Person.create! name: "Javan"
+    #     attachment = ActionText::Attachment.from_attachable(attachable)
+    #     attachment.to_html # => "<action-text-attachment sgid=\"BAh7CEk...
     def to_html
       HtmlConversion.node_to_html(node)
     end

data/lib/action_text/attachment_gallery.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   class AttachmentGallery
     include ActiveModel::Model

data/lib/action_text/attachments/caching.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   module Attachments
     module Caching

data/lib/action_text/attachments/minification.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   module Attachments
     module Minification

data/lib/action_text/attachments/trix_conversion.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/core_ext/object/try"
 
 module ActionText

data/lib/action_text/attribute.rb

@@ -1,40 +1,56 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   module Attribute
     extend ActiveSupport::Concern
 
     class_methods do
-      # Provides access to a dependent RichText model that holds the body and attachments for a single named rich text attribute.
-      # This dependent attribute is lazily instantiated and will be auto-saved when it's been changed. Example:
+      # Provides access to a dependent RichText model that holds the body and
+      # attachments for a single named rich text attribute. This dependent attribute
+      # is lazily instantiated and will be auto-saved when it's been changed. Example:
+      #
+      #     class Message < ActiveRecord::Base
+      #       has_rich_text :content
+      #     end
+      #
+      #     message = Message.create!(content: "<h1>Funny times!</h1>")
+      #     message.content? #=> true
+      #     message.content.to_s # => "<h1>Funny times!</h1>"
+      #     message.content.to_plain_text # => "Funny times!"
+      #
+      # The dependent RichText model will also automatically process attachments links
+      # as sent via the Trix-powered editor. These attachments are associated with the
+      # RichText model using Active Storage.
       #
-      #   class Message < ActiveRecord::Base
-      #     has_rich_text :content
-      #   end
+      # If you wish to preload the dependent RichText model, you can use the named
+      # scope:
       #
-      #   message = Message.create!(content: "<h1>Funny times!</h1>")
-      #   message.content? #=> true
-      #   message.content.to_s # => "<h1>Funny times!</h1>"
-      #   message.content.to_plain_text # => "Funny times!"
+      #     Message.all.with_rich_text_content # Avoids N+1 queries when you just want the body, not the attachments.
+      #     Message.all.with_rich_text_content_and_embeds # Avoids N+1 queries when you just want the body and attachments.
+      #     Message.all.with_all_rich_text # Loads all rich text associations.
       #
-      # The dependent RichText model will also automatically process attachments links as sent via the Trix-powered editor.
-      # These attachments are associated with the RichText model using Active Storage.
+      # #### Options
       #
-      # If you wish to preload the dependent RichText model, you can use the named scope:
+      # *   `:encrypted` - Pass true to encrypt the rich text attribute. The
+      #     encryption will be non-deterministic. See
+      #     `ActiveRecord::Encryption::EncryptableRecord.encrypts`. Default: false.
       #
-      #   Message.all.with_rich_text_content # Avoids N+1 queries when you just want the body, not the attachments.
-      #   Message.all.with_rich_text_content_and_embeds # Avoids N+1 queries when you just want the body and attachments.
-      #   Message.all.with_all_rich_text # Loads all rich text associations.
+      # *   `:strict_loading` - Pass true to force strict loading. When omitted,
+      #     `strict_loading:` will be set to the value of the
+      #     `strict_loading_by_default` class attribute (false by default).
       #
-      # ==== Options
+      # *   `:store_if_blank` - Pass false to not create RichText records with empty values,
+      #     if a blank value is provided. Default: true.
       #
-      # * <tt>:encrypted</tt> - Pass true to encrypt the rich text attribute. The encryption will be non-deterministic. See
-      #   +ActiveRecord::Encryption::EncryptableRecord.encrypts+. Default: false.
       #
-      # * <tt>:strict_loading</tt> - Pass true to force strict loading. When
-      #   omitted, <tt>strict_loading:</tt> will be set to the value of the
-      #   <tt>strict_loading_by_default</tt> class attribute (false by default).
-      def has_rich_text(name, encrypted: false, strict_loading: strict_loading_by_default)
+      # Note: Action Text relies on polymorphic associations, which in turn store
+      # class names in the database. When renaming classes that use `has_rich_text`,
+      # make sure to also update the class names in the
+      # `action_text_rich_texts.record_type` polymorphic type column of the
+      # corresponding rows.
+      def has_rich_text(name, encrypted: false, strict_loading: strict_loading_by_default, store_if_blank: true)
         class_eval <<-CODE, __FILE__, __LINE__ + 1
           def #{name}
             rich_text_#{name} || build_rich_text_#{name}
@@ -43,12 +59,29 @@ module ActionText
           def #{name}?
             rich_text_#{name}.present?
           end
-
-          def #{name}=(body)
-            self.#{name}.body = body
-          end
         CODE
 
+        if store_if_blank
+          class_eval <<-CODE, __FILE__, __LINE__ + 1
+            def #{name}=(body)
+              self.#{name}.body = body
+            end
+          CODE
+        else
+          class_eval <<-CODE, __FILE__, __LINE__ + 1
+            def #{name}=(body)
+              if body.present?
+                self.#{name}.body = body
+              else
+                if #{name}?
+                  self.#{name}.body = body
+                  self.#{name}.mark_for_destruction
+                end
+              end
+            end
+          CODE
+        end
+
         rich_text_class_name = encrypted ? "ActionText::EncryptedRichText" : "ActionText::RichText"
         has_one :"rich_text_#{name}", -> { where(name: name) },
           class_name: rich_text_class_name, as: :record, inverse_of: :record, autosave: true, dependent: :destroy,
@@ -60,9 +93,10 @@ module ActionText
 
       # Eager load all dependent RichText models in bulk.
       def with_all_rich_text
-        eager_load(rich_text_association_names)
+        includes(rich_text_association_names)
       end
 
+      # Returns the names of all rich text associations.
       def rich_text_association_names
         reflect_on_all_associations(:has_one).collect(&:name).select { |n| n.start_with?("rich_text_") }
       end

data/lib/action_text/content.rb

@@ -1,29 +1,32 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
-  # = Action Text \Content
+  # # Action Text Content
   #
-  # The +ActionText::Content+ class wraps an HTML fragment to add support for
+  # The `ActionText::Content` class wraps an HTML fragment to add support for
   # parsing, rendering and serialization. It can be used to extract links and
-  # attachments, convert the fragment to plain text, or serialize the fragment
-  # to the database.
+  # attachments, convert the fragment to plain text, or serialize the fragment to
+  # the database.
   #
   # The ActionText::RichText record serializes the `body` attribute as
-  # +ActionText::Content+.
+  # `ActionText::Content`.
   #
-  #   class Message < ActiveRecord::Base
-  #     has_rich_text :content
-  #   end
+  #     class Message < ActiveRecord::Base
+  #       has_rich_text :content
+  #     end
   #
-  #   message = Message.create!(content: "<h1>Funny times!</h1>")
-  #   body = message.content.body # => #<ActionText::Content "<div class=\"trix-conte...">
-  #   body.to_s # => "<h1>Funny times!</h1>"
-  #   body.to_plain_text # => "Funny times!"
+  #     message = Message.create!(content: "<h1>Funny times!</h1>")
+  #     body = message.content.body # => #<ActionText::Content "<div class=\"trix-conte...">
+  #     body.to_s # => "<h1>Funny times!</h1>"
+  #     body.to_plain_text # => "Funny times!"
   class Content
     include Rendering, Serialization, ContentHelper
 
     attr_reader :fragment
 
+    delegate :deconstruct, to: :fragment
     delegate :blank?, :empty?, :html_safe, :present?, to: :to_html # Delegating to to_html to avoid including the layout
 
     class << self
@@ -46,19 +49,19 @@ module ActionText
 
     # Extracts links from the HTML fragment:
     #
-    #   html = '<a href="http://example.com/">Example</a>'
-    #   content = ActionText::Content.new(html)
-    #   content.links # => ["http://example.com/"]
+    #     html = '<a href="http://example.com/">Example</a>'
+    #     content = ActionText::Content.new(html)
+    #     content.links # => ["http://example.com/"]
     def links
       @links ||= fragment.find_all("a[href]").map { |a| a["href"] }.uniq
     end
 
-    # Extracts +ActionText::Attachment+s from the HTML fragment:
+    # Extracts ActionText::Attachment objects from the HTML fragment:
     #
-    #   attachable = ActiveStorage::Blob.first
-    #   html = %Q(<action-text-attachment sgid="#{attachable.attachable_sgid}" caption="Captioned"></action-text-attachment>)
-    #   content = ActionText::Content.new(html)
-    #   content.attachments # => [#<ActionText::Attachment attachable=#<ActiveStorage::Blob...
+    #     attachable = ActiveStorage::Blob.first
+    #     html = %Q(<action-text-attachment sgid="#{attachable.attachable_sgid}" caption="Captioned"></action-text-attachment>)
+    #     content = ActionText::Content.new(html)
+    #     content.attachments # => [#<ActionText::Attachment attachable=#<ActiveStorage::Blob...
     def attachments
       @attachments ||= attachment_nodes.map do |node|
         attachment_for_node(node)
@@ -75,12 +78,12 @@ module ActionText
       @gallery_attachments ||= attachment_galleries.flat_map(&:attachments)
     end
 
-    # Extracts +ActionText::Attachable+s from the HTML fragment:
+    # Extracts ActionText::Attachable objects from the HTML fragment:
     #
-    #   attachable = ActiveStorage::Blob.first
-    #   html = %Q(<action-text-attachment sgid="#{attachable.attachable_sgid}" caption="Captioned"></action-text-attachment>)
-    #   content = ActionText::Content.new(html)
-    #   content.attachables # => [attachable]
+    #     attachable = ActiveStorage::Blob.first
+    #     html = %Q(<action-text-attachment sgid="#{attachable.attachable_sgid}" caption="Captioned"></action-text-attachment>)
+    #     content = ActionText::Content.new(html)
+    #     content.attachables # => [attachable]
     def attachables
       @attachables ||= attachment_nodes.map do |node|
         ActionText::Attachable.from_node(node)
@@ -110,10 +113,21 @@ module ActionText
       self.class.new(content, canonicalize: false)
     end
 
-    # Returns the content as plain text with all HTML tags removed.
+    # Returns a plain-text version of the markup contained by the content, with tags
+    # removed but HTML entities encoded.
+    #
+    #     content = ActionText::Content.new("<h1>Funny times!</h1>")
+    #     content.to_plain_text # => "Funny times!"
+    #
+    #     content = ActionText::Content.new("<div onclick='action()'>safe<script>unsafe</script></div>")
+    #     content.to_plain_text # => "safeunsafe"
     #
-    #   content = ActionText::Content.new("<h1>Funny times!</h1>")
-    #   content.to_plain_text # => "Funny times!"
+    # NOTE: that the returned string is not HTML safe and should not be rendered in
+    # browsers without additional sanitization.
+    #
+    #     content = ActionText::Content.new("&lt;script&gt;alert()&lt;/script&gt;")
+    #     content.to_plain_text # => "<script>alert()</script>"
+    #     ActionText::ContentHelper.sanitizer.sanitize(content.to_plain_text) # => ""
     def to_plain_text
       render_attachments(with_full_attributes: false, &:to_plain_text).fragment.to_plain_text
     end
@@ -134,6 +148,13 @@ module ActionText
       "action_text/contents/content"
     end
 
+    # Safely transforms Content into an HTML String.
+    #
+    #     content = ActionText::Content.new(content: "<h1>Funny times!</h1>")
+    #     content.to_s # => "<h1>Funny times!</h1>"
+    #
+    #     content = ActionText::Content.new("<div onclick='action()'>safe<script>unsafe</script></div>")
+    #     content.to_s # => "<div>safeunsafe</div>"
     def to_s
       to_rendered_html_with_layout
     end

data/lib/action_text/deprecator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   def self.deprecator # :nodoc:
     @deprecator ||= ActiveSupport::Deprecation.new

data/lib/action_text/encryption.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   module Encryption
     def encrypt

data/lib/action_text/engine.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "rails"
 require "action_controller/railtie"
 require "active_record/railtie"
 require "active_storage/engine"
 
 require "action_text"
+require "action_text/trix"
 
 module ActionText
   class Engine < Rails::Engine
@@ -32,7 +35,7 @@ module ActionText
 
     initializer "action_text.asset" do
       if Rails.application.config.respond_to?(:assets)
-        Rails.application.config.assets.precompile += %w( actiontext.js actiontext.esm.js trix.js trix.css )
+        Rails.application.config.assets.precompile += %w( actiontext.js actiontext.esm.js )
       end
     end
 
@@ -85,7 +88,9 @@ module ActionText
 
     config.after_initialize do |app|
       if klass = app.config.action_text.sanitizer_vendor
-        ActionText::ContentHelper.sanitizer = klass.safe_list_sanitizer.new
+        ActiveSupport.on_load(:action_view) do
+          ActionText::ContentHelper.sanitizer = klass.safe_list_sanitizer.new
+        end
       end
     end
   end

data/lib/action_text/fixture_set.rb

@@ -1,68 +1,68 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
-  # = Action Text \FixtureSet
+  # # Action Text FixtureSet
   #
-  # Fixtures are a way of organizing data that you want to test against; in
-  # short, sample data.
+  # Fixtures are a way of organizing data that you want to test against; in short,
+  # sample data.
   #
   # To learn more about fixtures, read the ActiveRecord::FixtureSet documentation.
   #
-  # === YAML
+  # ### YAML
   #
   # Like other Active Record-backed models, ActionText::RichText records inherit
-  # from ActiveRecord::Base instances and can therefore be populated by
-  # fixtures.
+  # from ActiveRecord::Base instances and can therefore be populated by fixtures.
   #
-  # Consider an <tt>Article</tt> class:
+  # Consider an `Article` class:
   #
-  #   class Article < ApplicationRecord
-  #     has_rich_text :content
-  #   end
+  #     class Article < ApplicationRecord
+  #       has_rich_text :content
+  #     end
   #
-  # To declare fixture data for the related <tt>content</tt>, first declare fixture
-  # data for <tt>Article</tt> instances in <tt>test/fixtures/articles.yml</tt>:
+  # To declare fixture data for the related `content`, first declare fixture data
+  # for `Article` instances in `test/fixtures/articles.yml`:
   #
-  #   first:
-  #     title: An Article
+  #     first:
+  #       title: An Article
   #
   # Then declare the ActionText::RichText fixture data in
-  # <tt>test/fixtures/action_text/rich_texts.yml</tt>, making sure to declare
-  # each entry's <tt>record:</tt> key as a polymorphic relationship:
+  # `test/fixtures/action_text/rich_texts.yml`, making sure to declare each
+  # entry's `record:` key as a polymorphic relationship:
   #
-  #   first:
-  #     record: first (Article)
-  #     name: content
-  #     body: <div>Hello, world.</div>
+  #     first:
+  #       record: first (Article)
+  #       name: content
+  #       body: <div>Hello, world.</div>
   #
   # When processed, Active Record will insert database records for each fixture
   # entry and will ensure the Action Text relationship is intact.
   class FixtureSet
-    # Fixtures support Action Text attachments as part of their <tt>body</tt>
-    # HTML.
+    # Fixtures support Action Text attachments as part of their `body` HTML.
     #
-    # === Examples
+    # ### Examples
     #
-    # For example, consider a second <tt>Article</tt> fixture declared in
-    # <tt>test/fixtures/articles.yml</tt>:
+    # For example, consider a second `Article` fixture declared in
+    # `test/fixtures/articles.yml`:
     #
-    #   second:
-    #     title: Another Article
+    #     second:
+    #       title: Another Article
     #
-    # You can attach a mention of <tt>articles(:first)</tt> to <tt>second</tt>'s
-    # <tt>content</tt> by embedding a call to <tt>ActionText::FixtureSet.attachment</tt>
-    # in the <tt>body:</tt> value in <tt>test/fixtures/action_text/rich_texts.yml</tt>:
+    # You can attach a mention of `articles(:first)` to `second`'s `content` by
+    # embedding a call to `ActionText::FixtureSet.attachment` in the `body:` value
+    # in `test/fixtures/action_text/rich_texts.yml`:
     #
-    #   second:
-    #     record: second (Article)
-    #     name: content
-    #     body: <div>Hello, <%= ActionText::FixtureSet.attachment("articles", :first) %></div>
+    #     second:
+    #       record: second (Article)
+    #       name: content
+    #       body: <div>Hello, <%= ActionText::FixtureSet.attachment("articles", :first) %></div>
     #
     def self.attachment(fixture_set_name, label, column_type: :integer)
       signed_global_id = ActiveRecord::FixtureSet.signed_global_id fixture_set_name, label,
         column_type: column_type, for: ActionText::Attachable::LOCATOR_NAME
 
-      %(<action-text-attachment sgid="#{signed_global_id}"></action-text-attachment>)
+      %(<#{Attachment.tag_name} sgid="#{signed_global_id}"></#{Attachment.tag_name}>)
     end
   end
 end

data/lib/action_text/fragment.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   class Fragment
     class << self
@@ -21,6 +23,8 @@ module ActionText
 
     attr_reader :source
 
+    delegate :deconstruct, to: "source.elements"
+
     def initialize(source)
       @source = source
     end

data/lib/action_text/gem_version.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
-  # Returns the currently loaded version of Action Text as a +Gem::Version+.
+  # Returns the currently loaded version of Action Text as a `Gem::Version`.
   def self.gem_version
     Gem::Version.new VERSION::STRING
   end
 
   module VERSION
-    MAJOR = 7
+    MAJOR = 8
     MINOR = 1
-    TINY  = 5
-    PRE   = "2"
+    TINY  = 2
+    PRE   = "1"
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
   end

data/lib/action_text/html_conversion.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   module HtmlConversion
     extend self