rails-domternal 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5648277022380eaaf7c2e1f337474924ca9bb1758698d2aa552e7d1ba03f9ae7
-  data.tar.gz: 9afacf5e4682b49222aef0c38a7fe0b744bf215268cf6564b7ddbc5616a4e6be
+  metadata.gz: 1ff0118eed2f74446b2b4d18eae2ae42d905b3875f6bcf1dc253e116a2a10fb0
+  data.tar.gz: 355c02ba5479fa07c42242850dd03367c32d7447015deb4b2c8f4a13d265154f
 SHA512:
-  metadata.gz: 99b5adcbf3a02f8b2ed0612084ab67581898d743cc3f9c35bff333a4f19c7c8766d3ad1df6d310ea60d8f9398242ceafa1d987c476bccf3e583dbbd49c5a2298
-  data.tar.gz: 65993a4507b4400482809116c71e611381b2dbcff12cc085f32132e7e69ca8ec7193ec7ca754ccf2bbe0ff9506a0a23f2e41ecaee7cc2b971e515dfec8e69dbb
+  metadata.gz: 7762281bd24200520b2e9612b3c7fba7ab032c65e5b6b0dcb632ab1f100f6fe5f66159a67d2cd3d5b460b73c461ea51351ecabbff9c26155507f4e77378effa1
+  data.tar.gz: a84961c1d821ae90784fb1fdb8dc75665171fae96a830a591c263bff4b85e6f538a7c8997318a0ddb776c3b3afcde3a18a6779fcdd3c51f9d7922aa957604078

data/README.md

@@ -52,6 +52,67 @@ Configure defaults in `config/initializers/domternal.rb` (generated by the insta
 see `Rails::Domternal::Configuration` for the full list of options (default extensions,
 toolbar, theme, sanitizer allowlist, upload limits).
 
+`#to_plain_text` converts a body to text the way ActionText does: block boundaries and
+`<br>` become newlines rather than collapsing into spaces, so line-oriented content (one
+list entry or answer per line) survives, and search columns built from rich text stay
+readable. `blank?`/`present?`/`empty?` delegate to it.
+
+### simple_form
+
+If your app has [simple_form](https://github.com/heartcombo/simple_form), `as: :domternal_area`
+works out of the box — the input is registered only when simple_form is loaded, and an
+app-defined `app/inputs/domternal_area_input.rb` takes precedence:
+
+```erb
+<%= f.input :body, as: :domternal_area %>
+```
+
+### Primary key types
+
+`domternal_rich_texts.record_id` holds the primary key of every model declaring
+`has_rich_domternal`, so it has to fit all of them. Both column types default to your
+`config.generators` `primary_key_type`, and can be overridden — but only *before* you run
+the migration, since that's when they're read:
+
+```ruby
+Rails::Domternal.configure do |config|
+  config.primary_key_type = :uuid
+  config.record_id_type = :string # models don't all share one key type
+end
+```
+
+If some models use uuid primary keys and others bigint, neither fits: use `:string`.
+
+## Migrating from ActionText
+
+```bash
+bin/rails g domternal:migrate_from_action_text
+bin/rails db:migrate
+```
+
+This writes a reversible data migration that copies every `action_text_rich_texts` row into
+`domternal_rich_texts`. Bodies carry over as-is (both store sanitized HTML), and the
+`<action-text-attachment>` nodes Domternal has no equivalent for are rewritten:
+
+- Image attachments become `<img>` tags pointing at the Active Storage redirect URL — the
+  same markup the editor's own upload handler writes — and the blobs are re-attached as
+  `Domternal::RichText` embeds.
+- Your own `ActionText::Attachable` models are dropped unless you say what they should
+  render as:
+
+  ```bash
+  bin/rails g domternal:migrate_from_action_text --attachment-partials HtmlTable:content
+  ```
+
+  which inlines `html_table.content` in place of each attachment node.
+
+`action_text_rich_texts` is left untouched, so the migration can be rolled back. Then swap
+`has_rich_text` for `has_rich_domternal`, `f.rich_text_area` for `f.domternal_area`, and the
+`.trix-content` class for `.domternal-content`.
+
+If you relied on an `ActionText::Attachable` model purely to embed tables, the `:table`
+extension replaces it — tables become real `<table>` markup the editor edits natively.
+
 ### Extensions
 
 Extensions are referenced by symbolic name (`:starter_kit`, `:image`, `:table`, `:mention`,
@@ -96,14 +157,43 @@ generates a `@apply`-based version wired into your existing Tailwind build; othe
 generates plain CSS under `app/assets/stylesheets/`. Force either explicitly with
 `rails g domternal:install --stylesheet=tailwind` (or `=css`).
 
+### Deferred mounting
+
+Editors mount when they first become visible, not on `connectedCallback`. Each one loads its
+extension modules and builds a ProseMirror instance, so a form with an editor per locale (or
+per tab, or inside a collapsed section) would otherwise pay for all of them on page load.
+
+An editor that hasn't mounted never writes to its hidden input, so the value the server
+rendered is what gets submitted — leaving a tab untouched is always safe. Opt out per editor
+with the `eager` attribute, and use `await element.ready()` to force mounting before driving
+an editor from your own JavaScript.
+
 ### JavaScript delivery
 
-The install generator pins `@domternal/*` packages from [esm.sh](https://esm.sh) by default
-for importmap apps. Cross-package peer dependencies (`@domternal/core`, `@domternal/pm`) are
-explicitly shared via `?external=` params and a `@domternal/pm/` prefix pin — omitting this
-causes ProseMirror's plugin registry to load twice and crash with "Adding different
-instances of a keyed plugin." For jsbundling/npm apps, the generator installs the real npm
-packages and copies the gem's JS source into `app/javascript/domternal`.
+Two setups, and the choice matters more than it looks:
+
+**Importmap (default).** The generator pins `@domternal/*` from [esm.sh](https://esm.sh) at
+an exact version resolved at install time. Cross-package peer dependencies
+(`@domternal/core`, `@domternal/pm`) are explicitly shared via `?external=` params and a
+`@domternal/pm/` prefix pin — omitting this loads ProseMirror's plugin registry twice and
+crashes with "Adding different instances of a keyed plugin."
+
+This is the quickest way to get running, but the editor is then fetched from a third-party
+CDN in the browser on every page that uses one: an outage or slow response degrades your
+admin UI, and the request graph is deep (the packages pull in ~12 ProseMirror modules).
+
+**Bundled (recommended for production).** With a `package.json` present, the generator runs
+`npm add`/`bun add` for the real packages and copies the gem's JS into
+`app/javascript/domternal`, so your bundler resolves and ships everything at build time —
+no runtime CDN, one copy of each dependency guaranteed by the resolver. To move an existing
+importmap app over, add [jsbundling-rails](https://github.com/rails/jsbundling-rails) and
+re-run `rails g domternal:install`, then drop the `@domternal/*` pins from
+`config/importmap.rb`.
+
+There's deliberately no "vendor the CDN files into `vendor/javascript`" option: esm.sh URLs
+embed semver ranges and resolve server-side, so downloading that graph correctly means
+reimplementing package resolution, and getting it subtly wrong produces duplicate ProseMirror
+instances that only fail at runtime. Use a bundler for that job.
 
 ## Development
 

data/app/assets/javascripts/domternal/element.js

@@ -13,17 +13,67 @@ export class DomternalEditorElement extends HTMLElement {
 
   connectedCallback() {
     if (this._mounted) return
-    this._mounted = true
-    this._mount()
+
+    // Editors that aren't on screen yet (locale tabs, accordions, anything display:none)
+    // wait to mount. Each one pulls its own extension modules and builds a ProseMirror
+    // instance, so a form with one editor per locale would otherwise pay for all of them
+    // up front. Setting the `eager` attribute opts out.
+    if (this.hasAttribute("eager") || !this._canDeferMount()) {
+      this._startMount()
+    } else {
+      this._observeVisibility()
+    }
   }
 
   disconnectedCallback() {
+    this._visibilityObserver?.disconnect()
+    this._visibilityObserver = null
     this._toolbar?.destroy()
     this._bubbleMenu?.destroy()
     this._floatingMenu?.destroy()
     this._notionColorPicker?.destroy()
     this._wrapper?.destroy()
     this._mounted = false
+    this._mountPromise = null
+  }
+
+  // Mounts now if the element is already laid out, otherwise once it first becomes visible.
+  _observeVisibility() {
+    if (this._isVisible()) {
+      this._startMount()
+      return
+    }
+
+    this._visibilityObserver = new IntersectionObserver((entries) => {
+      if (!entries.some((entry) => entry.isIntersecting)) return
+      this._visibilityObserver?.disconnect()
+      this._visibilityObserver = null
+      this._startMount()
+    })
+    this._visibilityObserver.observe(this)
+  }
+
+  _canDeferMount() {
+    return typeof IntersectionObserver !== "undefined"
+  }
+
+  _isVisible() {
+    return this.offsetParent !== null || this.getClientRects().length > 0
+  }
+
+  _startMount() {
+    if (!this._mountPromise) {
+      this._mounted = true
+      this._mountPromise = this._mount()
+    }
+    return this._mountPromise
+  }
+
+  // Resolves once the editor is mounted, mounting it immediately if it was still deferred.
+  // Use before reading `value` or driving the editor from outside.
+  async ready() {
+    await this._startMount()
+    return this
   }
 
   attributeChangedCallback(name, _oldValue, newValue) {
@@ -37,9 +87,11 @@ export class DomternalEditorElement extends HTMLElement {
     return id ? document.getElementById(id) : null
   }
 
-  // The wrapper's current HTML, or "" before the editor has mounted.
+  // The editor's current HTML. Falls back to the linked input while the editor is still
+  // deferred or mounting — an unmounted editor never touches the input, so the value the
+  // server rendered is still the right answer and submitting the form is always safe.
   get value() {
-    return this._wrapper?.htmlContent ?? ""
+    return this._wrapper?.htmlContent ?? this.input?.value ?? ""
   }
 
   async _mount() {

data/app/helpers/domternal/tag_helper.rb

@@ -29,8 +29,8 @@ module Domternal
       options[:class] ||= "domternal-content"
 
       options[:data] ||= {}
-      options[:data][:direct_upload_url] ||= main_app.rails_direct_uploads_url
-      options[:data][:blob_url_template] ||= main_app.rails_service_blob_url(":signed_id", ":filename")
+      options[:data][:direct_upload_url] ||= app_routes.rails_direct_uploads_url
+      options[:data][:blob_url_template] ||= app_routes.rails_service_blob_url(":signed_id", ":filename")
       options[:data][:extensions] ||= extensions.join(" ")
       options[:data][:toolbar] ||= toolbar.to_s
       options[:data][:theme] ||= Rails::Domternal.configuration.theme.to_s
@@ -38,7 +38,7 @@ module Domternal
       options[:data][:allowed_mime_types] ||= Rails::Domternal.configuration.allowed_mime_types.join(" ")
 
       editor_tag = content_tag("domternal-editor", "", options)
-      input_tag = hidden_field_tag(name, value.to_s, id: options[:input], form: form)
+      input_tag = hidden_field_tag(name, attribute_value(value), id: options[:input], form: form)
 
       input_tag + editor_tag
     end
@@ -46,6 +46,27 @@ module Domternal
     def domternal_content(value)
       content_tag(:div, value.to_s.html_safe, class: "domternal-content") # rubocop:disable Rails/OutputSafety -- sanitized by Domternal::RichText before persistence
     end
+
+    private
+
+    # The body lands in a value="…" attribute, but RichText#to_s is html_safe, and Rails
+    # skips escaping for html_safe strings even inside attributes. Handing it over as a plain
+    # String restores escaping — without this a body containing a double quote closes the
+    # attribute early, losing content on the next edit and allowing attribute injection.
+    def attribute_value(value)
+      string = value.to_s
+      string.html_safe? ? String.new(string) : string
+    end
+
+    # The Active Storage routes live in the host app. `main_app` is the right way to reach
+    # them from a view, but it's only defined where the mounted-helpers module has been
+    # included, which isn't every context this helper can be called from (mailers, bare
+    # ActionView::Base instances, ViewComponent previews).
+    def app_routes
+      return main_app if respond_to?(:main_app)
+
+      ::Rails.application.routes.url_helpers
+    end
   end
 end
 

data/app/models/domternal/rich_text.rb

@@ -6,6 +6,17 @@ module Domternal
   # (Domternal's `Editor`/`DomternalEditor` accept HTML directly as `content`), so no
   # separate JSON<->HTML conversion step is needed on the Ruby side.
   class RichText < ActiveRecord::Base
+    # How #to_plain_text separates elements: paragraph-level blocks get a blank line between
+    # them, list items and table rows a single newline, and table cells a space.
+    PARAGRAPH_TAGS = %w[
+      p div h1 h2 h3 h4 h5 h6 blockquote pre figure figcaption ul ol table details
+    ].freeze
+    LINE_TAGS = %w[li tr summary].freeze
+    CELL_TAGS = %w[td th].freeze
+    # Private-use codepoint: not whitespace, so the collapse in #to_plain_text leaves it
+    # alone, and Nokogiri accepts it in a text node (unlike NUL).
+    BREAK = "\uE000"
+
     self.table_name = "domternal_rich_texts"
 
     belongs_to :record, polymorphic: true, touch: true
@@ -20,12 +31,36 @@ module Domternal
       body.to_s.html_safe # rubocop:disable Rails/OutputSafety -- sanitized in #sanitize_body before persistence
     end
 
+    # Block-aware, like ActionText's plain text conversion: block boundaries and <br> become
+    # newlines rather than being collapsed into spaces. Callers rely on this — line-oriented
+    # content (one list item or answer per line) has to survive the round trip, and search
+    # index columns built from rich text read far better with the structure kept.
     def to_plain_text
-      body.to_s.gsub(/<[^>]*>/, " ").gsub(/\s+/, " ").strip
+      html = body.to_s
+      return "" if html.blank?
+
+      fragment = Nokogiri::HTML5.fragment(html)
+      # Breaks are marked with a sentinel rather than a real newline so that the whitespace
+      # collapse below can't tell them apart from incidental newlines in the source markup.
+      fragment.css("br").each { |node| node.replace(text_node(node, BREAK)) }
+      fragment.css(*CELL_TAGS).each { |node| node.add_next_sibling(text_node(node, " ")) }
+      fragment.css(*LINE_TAGS).each { |node| node.add_next_sibling(text_node(node, BREAK)) }
+      fragment.css(*PARAGRAPH_TAGS).each { |node| node.add_next_sibling(text_node(node, BREAK * 2)) }
+
+      fragment.text
+        .gsub(/[^\S\n]+/, " ")  # spaces and tabs collapse; newlines in text are content
+        .gsub(/ ?(#{BREAK}(?: ?#{BREAK})*) ?/o) { "\n" * Regexp.last_match(1).count(BREAK) }
+        .gsub(/ *\n */, "\n")
+        .gsub(/\n{3,}/, "\n\n")
+        .strip
     end
 
     private
 
+    def text_node(node, content)
+      Nokogiri::XML::Text.new(content, node.document)
+    end
+
     def sanitize_body
       return if body.blank?
 
@@ -47,7 +82,14 @@ module Domternal
       return if body.blank?
 
       signed_ids = body.to_s.scan(%r{/rails/active_storage/blobs/(?:redirect|proxy)/([^/]+)/}).flatten.uniq
-      self.embeds = signed_ids.filter_map { |signed_id| ActiveStorage::Blob.find_signed(signed_id) }
+      blobs = signed_ids.filter_map { |signed_id| ActiveStorage::Blob.find_signed(signed_id) }
+
+      # Only reassign when the set actually changed: `embeds=` replaces every attachment row
+      # and re-runs Active Storage's identify pass (which downloads a chunk of each blob), so
+      # doing it on every save of an unchanged body is needless work.
+      return if blobs.map(&:id).to_set == embeds_blobs.map(&:id).to_set
+
+      self.embeds = blobs
     end
   end
 end

data/db/migrate/20260101000000_create_domternal_tables.rb

@@ -1,25 +1,31 @@
 class CreateDomternalTables < ActiveRecord::Migration[7.1]
   def change
-    primary_key_type, foreign_key_type = primary_and_foreign_key_types
-
     create_table :domternal_rich_texts, id: primary_key_type do |t|
       t.string :name, null: false
       t.text :body
-      t.references :record, null: false, polymorphic: true, index: false, type: foreign_key_type
+      t.references :record, null: false, polymorphic: true, index: false, type: record_id_type
 
       t.timestamps
 
-      t.index [:record_type, :record_id, :name], name: "index_domternal_rich_texts_uniqueness", unique: true
+      t.index [ :record_type, :record_id, :name ], name: "index_domternal_rich_texts_uniqueness", unique: true
     end
   end
 
   private
 
-  def primary_and_foreign_key_types
+  def primary_key_type
+    Rails::Domternal.configuration.primary_key_type || generators_primary_key_type || :primary_key
+  end
+
+  # `record_id` has to hold the primary key of every model that declares has_rich_domternal.
+  # An app whose models don't all share one key type (say uuid alongside bigint) needs
+  # :string here — see config.record_id_type in config/initializers/domternal.rb.
+  def record_id_type
+    Rails::Domternal.configuration.record_id_type || generators_primary_key_type || :bigint
+  end
+
+  def generators_primary_key_type
     config = Rails.configuration.generators
-    setting = config.options[config.orm][:primary_key_type]
-    primary_key_type = setting || :primary_key
-    foreign_key_type = setting || :bigint
-    [primary_key_type, foreign_key_type]
+    config.options[config.orm][:primary_key_type]
   end
 end

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

@@ -37,8 +37,9 @@ module Domternal
         @domternal/extension-toc @domternal/extension-block-controls @domternal/extension-details
       ].index_with { [CORE_PACKAGE, PM_PACKAGE] }.freeze
 
-      class_option :npm_version, type: :string, default: "latest",
-        desc: "Version/dist-tag used when pinning @domternal/* packages"
+      class_option :npm_version, type: :string, default: nil,
+        desc: "Version/dist-tag used when pinning @domternal/* packages. Defaults to the " \
+          "version currently on npm, resolved once so the pins are reproducible."
 
       class_option :stylesheet, type: :string, default: nil, enum: %w[css tailwind],
         desc: "Format for the generated content typography stylesheet. Defaults to " \
@@ -89,8 +90,25 @@ module Domternal
 
       private
 
+      # Resolved once and reused for every pin. A dist-tag like "latest" in the importmap
+      # would mean the browser silently picks up new editor versions between deploys, and —
+      # worse — different @domternal/* packages could resolve to different versions mid-page.
       def npm_version
-        options["npm_version"]
+        @npm_version ||= options["npm_version"] || latest_npm_version || "latest"
+      end
+
+      def latest_npm_version
+        require "net/http"
+        require "json"
+
+        response = Net::HTTP.get_response(URI("https://registry.npmjs.org/@domternal%2Fcore"))
+        return unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body).dig("dist-tags", "latest")
+      rescue StandardError => e
+        say "Could not reach the npm registry to resolve a version (#{e.class}); " \
+          "pinning \"latest\" instead — set an exact version in config/importmap.rb.", :yellow
+        nil
       end
 
       def using_importmap?
@@ -139,22 +157,36 @@ module Domternal
       def wire_up_importmap
         importmap_path = Pathname(destination_root).join("config/importmap.rb")
 
-        pins = +"\n# rails-domternal\n"
+        pins = +<<~HEADER
+          \n# rails-domternal. The @domternal/* packages are loaded from esm.sh at runtime, so
+          # the editor depends on that CDN being reachable from your users' browsers. Every
+          # consumer must externalize the same peers, otherwise esm.sh inlines a second copy of
+          # ProseMirror and keyed plugins collide. To take the CDN off the critical path, use
+          # the jsbundling setup instead — see the README.
+        HEADER
         pins << %(pin_all_from Rails::Domternal::Engine.root.join("app/assets/javascripts/domternal"), under: "domternal", preload: true\n)
         pins << %(pin "@rails/activestorage", to: "activestorage.esm.js", preload: true\n) unless
           importmap_path.read.include?('"@rails/activestorage"')
 
-        pins << %(pin "#{PM_PACKAGE}/", to: "https://esm.sh/#{PM_PACKAGE}@#{npm_version}/"\n)
+        # Nothing from esm.sh is preloaded: element.js imports every @domternal/* package
+        # dynamically when an editor mounts, so preloading would make each page — including
+        # every page with no editor on it — fetch the editor bundle from the CDN up front.
+        pins << %(pin "#{PM_PACKAGE}/", to: "https://esm.sh/#{PM_PACKAGE}@#{npm_version}/", preload: false\n)
 
         all_packages.each do |package, externals|
           url = "https://esm.sh/#{package}@#{npm_version}"
           url += "?external=#{externals.join(",")}" if externals.present?
-          preload = package == CORE_PACKAGE
-          pins << %(pin "#{package}", to: "#{url}"#{preload ? "" : ", preload: false"}\n)
+          pins << %(pin "#{package}", to: "#{url}", preload: false\n)
         end
 
         append_to_file importmap_path.to_s, pins
-        say "Pinned domternal + @domternal/* packages (via esm.sh) in config/importmap.rb", :green
+        say "Pinned domternal + @domternal/* packages at #{npm_version} (via esm.sh) in config/importmap.rb", :green
+        say <<~WARNING, :yellow
+          These pins fetch the editor from esm.sh in the browser at runtime. That's fine for
+          getting started, but it puts a third-party CDN on the path of every page with an
+          editor. For production, prefer the jsbundling setup (npm + esbuild), which resolves
+          and bundles the packages at build time — see "Bundled setup" in the README.
+        WARNING
 
         application_js = Pathname(destination_root).join("app/javascript/application.js")
         if application_js.exist?

data/lib/generators/domternal/install/templates/initializer.rb

@@ -21,4 +21,14 @@ Rails::Domternal.configure do |config|
   # introduce markup not covered by the defaults.
   # config.sanitizer_allowed_tags += %w[]
   # config.sanitizer_allowed_attributes += %w[]
+
+  # Column types for the domternal_rich_texts table, read only when the CreateDomternalTables
+  # migration runs — set them BEFORE `bin/rails db:migrate`. Both default to your
+  # config.generators primary_key_type, then to Rails' defaults (:primary_key / :bigint).
+  #
+  # `record_id` stores the primary key of every model declaring has_rich_domternal, so if those
+  # models don't all share one key type — a uuid-pk model next to a bigint-pk one — neither
+  # :uuid nor :bigint fits and you want :string.
+  # config.primary_key_type = :uuid
+  # config.record_id_type = :string
 end

data/lib/generators/domternal/migrate_from_action_text/migrate_from_action_text_generator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+module Domternal
+  module Generators
+    # rails g domternal:migrate_from_action_text
+    #
+    # Copies every action_text_rich_texts row into domternal_rich_texts, rewriting the
+    # <action-text-attachment> nodes that Domternal has no equivalent for. Writes a normal
+    # timestamped migration so it runs through the usual deploy path and stays reversible.
+    class MigrateFromActionTextGenerator < ::Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :attachment_partials, type: :hash, default: {},
+        desc: "Map of attachable class name to a method returning its replacement HTML, " \
+          "e.g. --attachment-partials HtmlTable:content"
+
+      def create_migration_file
+        migration_template "migrate_action_text_to_domternal.rb.tt",
+          "db/migrate/migrate_action_text_to_domternal.rb"
+      end
+
+      def show_notes
+        say <<~NOTES, :green
+
+          Review the generated migration before running it. It:
+
+            * copies bodies verbatim (both use sanitized HTML, so no conversion is needed)
+            * turns image attachments into <img> tags on Active Storage redirect URLs, which
+              is the same markup the editor's upload handler writes
+            * re-attaches the referenced blobs as Domternal::RichText embeds
+            * leaves action_text_rich_texts untouched, so you can roll back
+
+          Non-image attachables (ActionText::Attachable models of your own) are dropped unless
+          you tell it what to render — see ATTACHABLE_REPLACEMENTS in the migration.
+        NOTES
+      end
+
+      private
+
+      def attachment_replacements
+        options["attachment_partials"]
+      end
+    end
+  end
+end

data/lib/generators/domternal/migrate_from_action_text/templates/migrate_action_text_to_domternal.rb.tt

@@ -0,0 +1,117 @@
+require "nokogiri"
+
+class MigrateActionTextToDomternal < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  # ActionText represents embeds as <action-text-attachment sgid="...">, which Domternal has
+  # no node for. Images become plain <img> pointing at the Active Storage redirect URL — the
+  # same markup app/assets/javascripts/domternal/direct_upload.js writes after an upload — so
+  # the editor round-trips them like any other image.
+  #
+  # Attachables of your own (ActionText::Attachable models) can't be guessed at. Map the class
+  # name to something returning replacement HTML, or leave it out and the node is dropped:
+  #
+  #   ATTACHABLE_REPLACEMENTS = {
+  #     "HtmlTable" => ->(record) { record.content },
+  #   }.freeze
+  ATTACHABLE_REPLACEMENTS = {
+<% attachment_replacements.each do |klass, method| -%>
+    "<%= klass %>" => ->(record) { record.<%= method %> },
+<% end -%>
+  }.freeze
+
+  # Read through bare AR models rather than the app's classes: ActionText::RichText#body
+  # returns rendered ActionText::Content, and the attachable class may already be gone.
+  class LegacyRichText < ActiveRecord::Base
+    self.table_name = "action_text_rich_texts"
+  end
+
+  def up
+    say "migrating #{LegacyRichText.count} action_text_rich_texts rows"
+    migrated = skipped = 0
+
+    # Nothing here should bump parent timestamps.
+    ActiveRecord::Base.no_touching do
+      LegacyRichText.find_each do |source|
+        if already_migrated?(source)
+          skipped += 1
+          next
+        end
+
+        Domternal::RichText.create!(
+          record_type: source.record_type,
+          record_id: source.record_id,
+          name: source.name,
+          body: convert(source.body),
+          created_at: source.created_at,
+          updated_at: source.updated_at
+        )
+        migrated += 1
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotFound => e
+        skipped += 1
+        say "  skipped #{source.record_type}##{source.record_id} #{source.name}: #{e.message}"
+      end
+    end
+
+    say "migrated #{migrated}, skipped #{skipped}"
+  end
+
+  def down
+    Domternal::RichText.delete_all
+  end
+
+  private
+
+  def already_migrated?(source)
+    Domternal::RichText.exists?(
+      record_type: source.record_type, record_id: source.record_id, name: source.name
+    )
+  end
+
+  def convert(html)
+    return html if html.blank? || !html.include?("action-text-attachment")
+
+    fragment = Nokogiri::HTML5.fragment(html)
+    fragment.css("action-text-attachment").each do |node|
+      replacement = replacement_for(node)
+      replacement ? node.replace(replacement) : node.remove
+    end
+    fragment.to_html
+  end
+
+  # The sgid is parsed rather than located, so an attachable class that no longer exists
+  # yields nil instead of raising NameError.
+  def replacement_for(node)
+    return if node["sgid"].blank?
+
+    gid = SignedGlobalID.parse(node["sgid"], for: "attachable")
+    return if gid.nil?
+
+    if gid.model_name == "ActiveStorage::Blob"
+      blob = ActiveStorage::Blob.find_by(id: gid.model_id)
+      blob && image_html(blob, node)
+    else
+      custom_replacement(gid)
+    end
+  end
+
+  def custom_replacement(gid)
+    replacement = ATTACHABLE_REPLACEMENTS[gid.model_name]
+    return unless replacement
+
+    record = gid.model_name.safe_constantize&.find_by(id: gid.model_id)
+    record && replacement.call(record)
+  end
+
+  def image_html(blob, node)
+    return unless blob.content_type.to_s.start_with?("image/")
+
+    filename = node["filename"].presence || blob.filename.to_s
+    url = "/rails/active_storage/blobs/redirect/#{blob.signed_id}/#{ERB::Util.url_encode(filename)}"
+    alt = node["alt"].presence || filename
+    img = %(<img src="#{ERB::Util.html_escape(url)}" alt="#{ERB::Util.html_escape(alt)}">)
+
+    caption = node["caption"].presence
+    return img if caption.blank?
+
+    %(<figure>#{img}<figcaption>#{ERB::Util.html_escape(caption)}</figcaption></figure>)
+  end
+end

data/lib/rails/domternal/configuration.rb

@@ -24,6 +24,15 @@ module Rails
       attr_accessor :allowed_mime_types
       attr_accessor :max_file_size
 
+      # Column types used by the CreateDomternalTables migration. Both default to the app's
+      # `config.generators` primary_key_type, then to Rails' defaults.
+      #
+      # Set record_id_type to :string if the models declaring has_rich_domternal don't all
+      # share one primary key type — a uuid-pk model and a bigint-pk model can't both be
+      # referenced by a typed polymorphic column. Only read at migration time.
+      attr_accessor :primary_key_type
+      attr_accessor :record_id_type
+
       # HTML tags/attributes allowed through the safelist sanitizer applied to incoming bodies.
       attr_accessor :sanitizer_allowed_tags
       attr_accessor :sanitizer_allowed_attributes
@@ -36,6 +45,8 @@ module Rails
         @npm_version = "latest"
         @allowed_mime_types = %w[image/png image/jpeg image/gif image/webp image/svg+xml image/avif]
         @max_file_size = 10.megabytes
+        @primary_key_type = nil
+        @record_id_type = nil
 
         @sanitizer_allowed_tags = %w[
           p br div span

data/lib/rails/domternal/engine.rb

@@ -32,6 +32,18 @@ module Rails
           include Rails::Domternal::Attribute
         end
       end
+
+      # Opt-in by presence: apps using simple_form get `as: :domternal_area` for free, apps
+      # without it never load the input. Runs after initialization so an app's own
+      # app/inputs/domternal_area_input.rb wins.
+      initializer "domternal.simple_form" do |app|
+        app.config.after_initialize do
+          next unless defined?(::SimpleForm)
+          next if Object.const_defined?(:DomternalAreaInput)
+
+          require "rails/domternal/simple_form_input"
+        end
+      end
     end
   end
 end

data/lib/rails/domternal/simple_form_input.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Loaded only when the host app has simple_form (see Engine's "domternal.simple_form"
+# initializer). simple_form resolves `as: :domternal_area` by constantizing
+# "DomternalAreaInput" at the top level, which is why this isn't namespaced.
+#
+#   <%= simple_form_for @post do |f| %>
+#     <%= f.input :body, as: :domternal_area %>
+#   <% end %>
+#
+# An app-defined app/inputs/domternal_area_input.rb takes precedence.
+class DomternalAreaInput < SimpleForm::Inputs::Base
+  def input(wrapper_options = nil)
+    merged_input_options = merge_wrapper_options(input_html_options, wrapper_options)
+    @builder.domternal_area(attribute_name, merged_input_options)
+  end
+end

data/lib/rails/domternal/version.rb

@@ -2,6 +2,6 @@
 
 module Rails
   module Domternal
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-domternal
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Stefan
@@ -47,12 +47,15 @@ files:
 - lib/generators/domternal/install/templates/domternal_content.css.erb
 - lib/generators/domternal/install/templates/domternal_content.tailwind.css.erb
 - lib/generators/domternal/install/templates/initializer.rb
+- lib/generators/domternal/migrate_from_action_text/migrate_from_action_text_generator.rb
+- lib/generators/domternal/migrate_from_action_text/templates/migrate_action_text_to_domternal.rb.tt
 - lib/rails-domternal.rb
 - lib/rails/domternal.rb
 - lib/rails/domternal/attribute.rb
 - lib/rails/domternal/configuration.rb
 - lib/rails/domternal/engine.rb
 - lib/rails/domternal/extension_registry.rb
+- lib/rails/domternal/simple_form_input.rb
 - lib/rails/domternal/version.rb
 - sig/rails/domternal.rbs
 homepage: https://github.com/getrestful/rails-domternal