actiontext 7.0.8.1 → 7.2.2.1

data/lib/action_text/attachable.rb

@@ -1,12 +1,33 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
+  # # Action Text Attachable
+  #
+  # Include this module to make a record attachable to an ActionText::Content.
+  #
+  #     class Person < ApplicationRecord
+  #       include ActionText::Attachable
+  #     end
+  #
+  #     person = Person.create! name: "Javan"
+  #     html = %Q(<action-text-attachment sgid="#{person.attachable_sgid}"></action-text-attachment>)
+  #     content = ActionText::Content.new(html)
+  #     content.attachables # => [person]
   module Attachable
     extend ActiveSupport::Concern
 
     LOCATOR_NAME = "attachable"
 
     class << self
+      # Extracts the `ActionText::Attachable` from the attachment HTML node:
+      #
+      #     person = Person.create! name: "Javan"
+      #     html = %Q(<action-text-attachment sgid="#{person.attachable_sgid}"></action-text-attachment>)
+      #     fragment = ActionText::Fragment.wrap(html)
+      #     attachment_node = fragment.find_all(ActionText::Attachment.tag_name).first
+      #     ActionText::Attachable.from_node(attachment_node) # => person
       def from_node(node)
         if attachable = attachable_from_sgid(node["sgid"])
           attachable
@@ -15,7 +36,7 @@ module ActionText
         elsif attachable = ActionText::Attachables::RemoteImage.from_node(node)
           attachable
         else
-          ActionText::Attachables::MissingAttachable
+          ActionText::Attachables::MissingAttachable.new(node["sgid"])
         end
       end
 
@@ -37,8 +58,24 @@ module ActionText
       def from_attachable_sgid(sgid)
         ActionText::Attachable.from_attachable_sgid(sgid, only: self)
       end
+
+      # Returns the path to the partial that is used for rendering missing
+      # attachables. Defaults to "action_text/attachables/missing_attachable".
+      #
+      # Override to render a different partial:
+      #
+      #     class User < ApplicationRecord
+      #       def self.to_missing_attachable_partial_path
+      #         "users/missing_attachable"
+      #       end
+      #     end
+      def to_missing_attachable_partial_path
+        ActionText::Attachables::MissingAttachable::DEFAULT_PARTIAL_PATH
+      end
     end
 
+    # Returns the Signed Global ID for the attachable. The purpose of the ID is set
+    # to 'attachable' so it can't be reused for other purposes.
     def attachable_sgid
       to_sgid(expires_in: nil, for: LOCATOR_NAME).to_s
     end
@@ -63,14 +100,30 @@ module ActionText
       false
     end
 
-    def as_json(*)
-      super.merge("attachable_sgid" => persisted? ? attachable_sgid : nil)
-    end
-
+    # Returns the path to the partial that is used for rendering the attachable in
+    # Trix. Defaults to `to_partial_path`.
+    #
+    # Override to render a different partial:
+    #
+    #     class User < ApplicationRecord
+    #       def to_trix_content_attachment_partial_path
+    #         "users/trix_content_attachment"
+    #       end
+    #     end
     def to_trix_content_attachment_partial_path
       to_partial_path
     end
 
+    # Returns the path to the partial that is used for rendering the attachable.
+    # Defaults to `to_partial_path`.
+    #
+    # Override to render a different partial:
+    #
+    #     class User < ApplicationRecord
+    #       def to_attachable_partial_path
+    #         "users/attachable"
+    #       end
+    #     end
     def to_attachable_partial_path
       to_partial_path
     end
@@ -86,5 +139,18 @@ module ActionText
         attrs[:height] = attachable_metadata[:height]
       end.compact
     end
+
+    private
+      def attribute_names_for_serialization
+        super + ["attachable_sgid"]
+      end
+
+      def read_attribute_for_serialization(key)
+        if key == "attachable_sgid"
+          persisted? ? super : nil
+        else
+          super
+        end
+      end
   end
 end

data/lib/action_text/attachables/content_attachment.rb

@@ -1,38 +1,42 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   module Attachables
-    class ContentAttachment
+    class ContentAttachment # :nodoc:
       include ActiveModel::Model
 
       def self.from_node(node)
-        if node["content-type"]
-          if matches = node["content-type"].match(/vnd\.rubyonrails\.(.+)\.html/)
-            attachment = new(name: matches[1])
-            attachment if attachment.valid?
-          end
-        end
+        attachment = new(content_type: node["content-type"], content: node["content"])
+        attachment if attachment.valid?
       end
 
-      attr_accessor :name
-      validates_inclusion_of :name, in: %w( horizontal-rule )
+      attr_accessor :content_type, :content
+
+      validates_format_of :content_type, with: /html/
+      validates_presence_of :content
 
       def attachable_plain_text_representation(caption)
-        case name
-        when "horizontal-rule"
-          " ┄ "
-        else
-          " "
-        end
+        content_instance.fragment.source
+      end
+
+      def to_html
+        @to_html ||= content_instance.render(content_instance)
+      end
+
+      def to_s
+        to_html
       end
 
       def to_partial_path
         "action_text/attachables/content_attachment"
       end
 
-      def to_trix_content_attachment_partial_path
-        "action_text/attachables/content_attachments/#{name.underscore}"
-      end
+      private
+        def content_instance
+          @content_instance ||= ActionText::Content.new(content)
+        end
     end
   end
 end

data/lib/action_text/attachables/missing_attachable.rb

@@ -1,12 +1,28 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   module Attachables
-    module MissingAttachable
+    class MissingAttachable
       extend ActiveModel::Naming
 
-      def self.to_partial_path
-        "action_text/attachables/missing_attachable"
+      DEFAULT_PARTIAL_PATH = "action_text/attachables/missing_attachable"
+
+      def initialize(sgid)
+        @sgid = SignedGlobalID.parse(sgid, for: ActionText::Attachable::LOCATOR_NAME)
+      end
+
+      def to_partial_path
+        if model
+          model.to_missing_attachable_partial_path
+        else
+          DEFAULT_PARTIAL_PATH
+        end
+      end
+
+      def model
+        @sgid&.model_name.to_s.safe_constantize
       end
     end
   end

data/lib/action_text/attachables/remote_image.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
   module Attachables
     class RemoteImage

data/lib/action_text/attachment.rb

@@ -1,14 +1,27 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/core_ext/object/try"
 
 module ActionText
+  # # Action Text Attachment
+  #
+  # Attachments serialize attachables to HTML or plain text.
+  #
+  #     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..."
   class Attachment
     include Attachments::TrixConversion, Attachments::Minification, Attachments::Caching
 
     mattr_accessor :tag_name, default: "action-text-attachment"
 
-    ATTRIBUTES = %w( sgid content-type url href filename filesize width height previewable presentation caption )
+    ATTRIBUTES = %w( sgid content-type url href filename filesize width height previewable presentation caption content )
 
     class << self
       def fragment_by_canonicalizing_attachments(content)
@@ -69,6 +82,31 @@ module ActionText
       self.class.from_attributes(full_attributes, attachable)
     end
 
+    # 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]"
+    #
+    # Use the `caption` when set:
+    #
+    #     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:
+    #
+    #     class Person < ApplicationRecord
+    #       include ActionText::Attachable
+    #
+    #       def attachable_plain_text_representation
+    #         "[#{name}]"
+    #       end
+    #     end
+    #
+    #     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)
@@ -77,6 +115,11 @@ module ActionText
       end
     end
 
+    # Converts the attachment to HTML.
+    #
+    #     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
@@ -91,7 +134,7 @@ module ActionText
 
     private
       def node_attributes
-        @node_attributes ||= ATTRIBUTES.map { |name| [ name.underscore, node[name] ] }.to_h.compact
+        @node_attributes ||= ATTRIBUTES.to_h { |name| [ name.underscore, node[name] ] }.compact
       end
 
       def attachable_attributes

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,36 +1,53 @@
 # 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
       #
-      #  * <tt>:encrypted</tt> - Pass true to encrypt the rich text attribute. The encryption will be non-deterministic. See
-      #  +ActiveRecord::Encryption::EncryptableRecord.encrypts+. Default: false.
-      def has_rich_text(name, encrypted: false)
+      # 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)
         class_eval <<-CODE, __FILE__, __LINE__ + 1
           def #{name}
             rich_text_#{name} || build_rich_text_#{name}
@@ -47,7 +64,8 @@ module ActionText
 
         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
+          class_name: rich_text_class_name, as: :record, inverse_of: :record, autosave: true, dependent: :destroy,
+          strict_loading: strict_loading
 
         scope :"with_rich_text_#{name}", -> { includes("rich_text_#{name}") }
         scope :"with_rich_text_#{name}_and_embeds", -> { includes("rich_text_#{name}": { embeds_attachments: :blob }) }
@@ -55,9 +73,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,11 +1,32 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionText
+  # # Action Text Content
+  #
+  # 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.
+  #
+  # The ActionText::RichText record serializes the `body` attribute as
+  # `ActionText::Content`.
+  #
+  #     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!"
   class Content
-    include Rendering, Serialization
+    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
@@ -26,10 +47,21 @@ module ActionText
       end
     end
 
+    # Extracts links from the HTML fragment:
+    #
+    #     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:
+    #
+    #     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)
@@ -46,6 +78,12 @@ module ActionText
       @gallery_attachments ||= attachment_galleries.flat_map(&:attachments)
     end
 
+    # Extracts +ActionText::Attachable+s 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]
     def attachables
       @attachables ||= attachment_nodes.map do |node|
         ActionText::Attachable.from_node(node)
@@ -59,6 +97,10 @@ module ActionText
 
     def render_attachments(**options, &block)
       content = fragment.replace(ActionText::Attachment.tag_name) do |node|
+        if node.key?("content")
+          sanitized_content = sanitize_content_attachment(node.remove_attribute("content").to_s)
+          node["content"] = sanitized_content if sanitized_content.present?
+        end
         block.call(attachment_for_node(node, **options))
       end
       self.class.new(content, canonicalize: false)
@@ -71,6 +113,20 @@ module ActionText
       self.class.new(content, canonicalize: false)
     end
 
+    # 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"
+    #
+    # NOTE: that the returned string is not HTML safe and should not be rendered in
+    # browsers.
+    #
+    #     content = ActionText::Content.new("&lt;script&gt;alert()&lt;/script&gt;")
+    #     content.to_plain_text # => "<script>alert()</script>"
     def to_plain_text
       render_attachments(with_full_attributes: false, &:to_plain_text).fragment.to_plain_text
     end
@@ -91,6 +147,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
@@ -100,11 +163,13 @@ module ActionText
     end
 
     def inspect
-      "#<#{self.class.name} #{to_s.truncate(25).inspect}>"
+      "#<#{self.class.name} #{to_html.truncate(25).inspect}>"
     end
 
     def ==(other)
-      if other.is_a?(self.class)
+      if self.class == other.class
+        to_html == other.to_html
+      elsif other.is_a?(self.class)
         to_s == other.to_s
       end
     end

data/lib/action_text/deprecator.rb

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

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,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "rails"
 require "action_controller/railtie"
 require "active_record/railtie"
@@ -19,6 +21,10 @@ module ActionText
       #{root}/app/models
     )
 
+    initializer "action_text.deprecator", before: :load_environment_config do |app|
+      app.deprecators[:action_text] = ActionText.deprecator
+    end
+
     initializer "action_text.attribute" do
       ActiveSupport.on_load(:active_record) do
         include ActionText::Attribute
@@ -28,7 +34,7 @@ module ActionText
 
     initializer "action_text.asset" do
       if Rails.application.config.respond_to?(:assets)
-        Rails.application.config.assets.precompile += %w( actiontext.js trix.js trix.css )
+        Rails.application.config.assets.precompile += %w( actiontext.js actiontext.esm.js trix.js trix.css )
       end
     end
 
@@ -51,20 +57,16 @@ module ActionText
     end
 
     initializer "action_text.helper" do
-      %i[action_controller_base action_mailer].each do |abstract_controller|
-        ActiveSupport.on_load(abstract_controller) do
+      %i[action_controller_base action_mailer].each do |base|
+        ActiveSupport.on_load(base) do
           helper ActionText::Engine.helpers
         end
       end
     end
 
     initializer "action_text.renderer" do
-      ActiveSupport.on_load(:action_text_content) do
-        self.default_renderer = Class.new(ActionController::Base).renderer
-      end
-
-      %i[action_controller_base action_mailer].each do |abstract_controller|
-        ActiveSupport.on_load(abstract_controller) do
+      %i[action_controller_base action_mailer].each do |base|
+        ActiveSupport.on_load(base) do
           around_action do |controller, action|
             ActionText::Content.with_renderer(controller, &action)
           end
@@ -82,5 +84,11 @@ module ActionText
     initializer "action_text.configure" do |app|
       ActionText::Attachment.tag_name = app.config.action_text.attachment_tag_name
     end
+
+    config.after_initialize do |app|
+      if klass = app.config.action_text.sanitizer_vendor
+        ActionText::ContentHelper.sanitizer = klass.safe_list_sanitizer.new
+      end
+    end
   end
 end