katalyst-content 3.2.2 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb3b9ee3efb967450397857049504a2fdc5e4cc845fbd9a53f3e51d728c578ba
-  data.tar.gz: b0befb4e9df360379236e4520f0e86a97f7daaaa4e3a38d83bf7066e2ce3def7
+  metadata.gz: 67386b67c7add01c35e38a9a2615c09fb56dbc3a77f74289671e3df3539e82ef
+  data.tar.gz: efbadc3abde98aaf0591b9ac8566c982b1d3c3094f7375b2e4555d8e21a269a9
 SHA512:
-  metadata.gz: b4d094dcd0b84d54d521e75b8d4cd75f766e957a15642dbc065f4a0fae00aa7646719a4f1dfa2fe7309481f32e74e02cf0db9d88ce0ecbc0c3fcbdcb3ffbeba6
-  data.tar.gz: 9666b55c1a490a23e2deb084f4277b75380ba759be9f2071a7b593287c7b05ea14be776ec4e5dc13275c4d2c0ec80a829aa6f3db2db5412857f1b7d6910294bc
+  metadata.gz: 74d3ac936c53778bee4c15cac9ced3ae219eb00f7338aba68d8ac713844e7a83fd74ee0a195b21fba03880fd8ad2a0d5e39f2e3d03f50931088de7134a263dba
+  data.tar.gz: 4649815a1c692d4b1d6ab7e30c99b4a76e605dbbe8f2771415a5e44eb90cbb716e55e3d46336e67a68530f33051f7e51e50781c5387a60438f930ebadad35377

data/README.md

@@ -1,232 +1,10 @@
-# Katalyst::Content
+# Katalyst Content
 
-Katalyst Content provides tools for creating and publishing content on Rails
-applications.
+A library for editing and publishing rich content in Ruby on Rails.
 
-## Installation
+## Documentation
 
-Install the gem as usual
-
-```ruby
-gem "katalyst-content"
-```
-
-Mount the engine in your `routes.rb` file:
-
-```ruby
-mount Katalyst::Content::Engine, at: "content"
-```
-
-Add the Gem's migrations to your application:
-
-```ruby
-rake katalyst_content:install:migrations
-```
-
-Add the Gem's javascript and CSS to your build pipeline. This assumes that
-you're using `propshaft` and `importmaps` to manage your assets.
-
-```javascript
-// app/javascript/controllers/application.js
-import { application } from "controllers/application";
-import content from "@katalyst/content";
-application.load(content);
-```
-
-Import the editor styles as css:
-
-```css
-/** In your admin/editor */
-@import url("/katalyst/content/editor.css");
-/** In your frontend */
-@import url("/katalyst/content/frontend.css");
-```
-
-Or, if you're using `dartsass-rails`:
-
-```scss
-// app/assets/stylesheets/admin.scss
-@use "katalyst/content/editor";
-// app/assets/stylesheets/application.scss
-@use "katalyst/content/frontend";
-```
-
-## Usage
-
-Content can be added to multiple models in your application. These examples
-assume a `Page` model.
-
-Assuming your model already exists, create a table for versions and add
-published and draft version columns to your model. For example, if you have a
-pages model:
-
-```ruby
-class CreatePageVersions < ActiveRecord::Migration[7.0]
-  def change
-    create_table :page_versions do |t|
-      t.references :parent, foreign_key: { to_table: :pages }, null: false
-      t.json :nodes
-
-      t.timestamps
-    end
-
-    change_table :pages do |t|
-      t.references :published_version, foreign_key: { to_table: :page_versions }
-      t.references :draft_version, foreign_key: { to_table: :page_versions }
-    end
-  end
-end
-```
-
-If you don't have a pages model yet, add it before the page_versions change:
-```ruby
-class CreatePages < ActiveRecord::Migration[7.0]
-  def change
-    create_table :pages do |t|
-      t.string :title
-      t.string :slug
-      t.boolean :show_title, default: true, null: false
-
-      t.timestamps
-    end
-    add_index :pages, :slug, unique: true
-
-    create_table :page_versions do |t|
-      t.references :parent, foreign_key: { to_table: :pages }, null: false
-      t.json :nodes
-
-      t.timestamps
-    end
-
-    change_table :pages do |t|
-      t.references :published_version, foreign_key: { to_table: :page_versions }
-      t.references :draft_version, foreign_key: { to_table: :page_versions }
-    end
-  end
-end
-```
-
-
-Next, include the `Katalyst::Content` concerns into your model, and add a nested
-model for storing content version information:
-
-```ruby
-class Page < ApplicationRecord
-  include Katalyst::Content::Container
-
-  class Version < ApplicationRecord
-    include Katalyst::Content::Version
-  end
-end
-```
-
-You may also want to configure your factory to add container information to
-items:
-
-```ruby
-FactoryBot.define do
-  factory :page do
-    title { Faker::Beer.unique.name }
-    slug { title.parameterize }
-
-    after(:build) do |page, _context|
-      page.items.each { |item| item.container = page }
-    end
-
-    after(:create) do |page, _context|
-      page.items_attributes = page.items.map.with_index { |item, index| { id: item.id, index: index, depth: 0 } }
-      page.publish!
-    end
-  end
-end
-```
-
-Create a controller for editing content. This example assumes you're rendering the editor on the 'show' route of an
-admin controller.
-
-```ruby
-class Admin::PagesController < Admin::BaseController
-  before_action :set_page, only: %i[show update]
-  
-  def show; end
-
-  def update
-    @page.attributes = page_params
-
-    unless @page.valid?
-      return respond_to do |format|
-        format.turbo_stream { render @editor.errors, status: :unprocessable_entity }
-      end
-    end
-
-    case params[:commit]
-    when "publish"
-      @page.save!
-      @page.publish!
-    when "save"
-      @page.save!
-    when "revert"
-      @page.revert!
-    end
-
-    redirect_to [:admin, @page], status: :see_other
-  end
-  
-  private
-  
-  def set_page
-    @page = Page.find(params[:id])
-    @editor = Katalyst::Content::EditorComponent.new(container: @page)
-  end
-
-  def page_params
-    params.require(:page).permit(items_attributes: %i[id index depth])
-  end
-end
-```
-
-And the view:
-
-```erb
-<%# app/views/admin/pages/show.html.erb %>
-<%= render @editor.status_bar %>
-<%= render @editor %>
-```
-
-### New items dialog customisation
-
-The new items dialog can be customised by providing content to the ViewComponent slot:
-
-```erb
-<%# app/views/admin/pages/show.html.erb %>
-<%= render @editor.status_bar %>
-<%= render @editor do |editor_component| %>
-  <% editor_component.with_new_items do |component| %>
-    <h3>Layouts</h3>
-    <ul role="list" class="items-list">
-      <%= component.item(:section) %>
-      <%= component.item(:group) %>
-      <%= component.item(:column) %>
-      <%= component.item(:aside) %>
-    </ul>
-    <h3>Content</h3>
-    <ul role="list" class="items-list">
-      <%= component.item(:content) %>
-      <%= component.item(:figure) %>
-      <%= component.item(:table) %>
-    </ul>
-  <% end %>
-<% end %>
-
-```
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run the tests.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
-version number and run `bundle exec rake release`, which will create a git tag for the version, push git commits and
-the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+See [katalyst.github.io/content](https://katalyst.github.io/content/) for documentation.
 
 ## Contributing
 
@@ -234,4 +12,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/kataly
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Katalyst Content is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/models/concerns/katalyst/content/duplicates_associations.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Content
+    # Copies declared associations when a record is duplicated, e.g. for
+    # copy-on-write. Intended for owned detail records that extend an STI
+    # item with attributes beyond the shared table:
+    #
+    #   has_one :detail, as: :detailable, autosave: true, dependent: :destroy
+    #   accepts_nested_attributes_for :detail, update_only: true
+    #   duplicates_association :detail
+    #
+    # Unsaved changes on the source's association are carried over to the
+    # duplicate. Records marked for destruction are dropped.
+    module DuplicatesAssociations
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :duplicated_associations, instance_writer: false, default: []
+      end
+
+      class_methods do
+        def duplicates_association(*names)
+          self.duplicated_associations += names.map(&:to_sym)
+        end
+      end
+
+      def initialize_dup(source)
+        super
+
+        duplicated_associations.each do |name|
+          macro = self.class.reflect_on_association(name).macro
+          DUPLICATORS.fetch(macro).new(name).apply(source, self)
+        end
+      end
+
+      # Duplicates a has_one association from source to target.
+      # Public API: can be used directly for models that want to duplicate a
+      # specific association without including the concern, e.g.
+      #   DuplicatesAssociations::DupOne.new(:detail).apply(source, self)
+      class DupOne
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+
+        def apply(source, target)
+          record = source.public_send(name)
+
+          target.public_send("#{name}=", record.dup) unless record.nil? || record.marked_for_destruction?
+        end
+      end
+
+      # Duplicates a has_many association from source to target.
+      # Public API: can be used directly for models that want to duplicate a
+      # specific association without including the concern, e.g.
+      #   DuplicatesAssociations::DupMany.new(:notes).apply(source, self)
+      class DupMany
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+
+        def apply(source, target)
+          records = source.public_send(name).reject(&:marked_for_destruction?).map(&:dup)
+
+          target.public_send("#{name}=", records) if records.any?
+        end
+      end
+
+      DUPLICATORS = {
+        has_one:  DupOne,
+        has_many: DupMany,
+      }.freeze
+    end
+  end
+end

data/app/models/concerns/katalyst/content/duplicates_attachments.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Content
+    # Copies ActiveStorage attachments when a record is duplicated, e.g. for
+    # copy-on-write. Pending changes on the source are carried over: new
+    # uploads are copied to the duplicate, while attachments that are being
+    # removed (either by assigning "" as govuk_attachment_field does, or via
+    # nested attributes with _destroy) are dropped from the duplicate.
+    module DuplicatesAttachments
+      extend ActiveSupport::Concern
+
+      def initialize_dup(source)
+        super
+
+        self.class.reflect_on_all_attachments.each do |reflection|
+          DUPLICATORS.fetch(reflection.macro).new(reflection.name).apply(source, self)
+        end
+      end
+
+      # Duplicates a has_one_attached attachment from source to target.
+      # Public API: can be used directly for models that want to duplicate a
+      # specific attachment without including the concern, e.g.
+      #   DuplicatesAttachments::DupOne.new(:image).apply(source, self)
+      class DupOne
+        attr_reader :name
+
+        def initialize(name)
+          @name = name.to_s
+        end
+
+        def apply(source, target)
+          current = source.public_send(name)
+          change  = source.attachment_changes[name]
+
+          # if attachment has changed, duplicate the change, otherwise attach the existing blob
+          if change.is_a?(ActiveStorage::Attached::Changes::CreateOne)
+            target.public_send("#{name}=", change.attachable)
+          elsif change.is_a?(ActiveStorage::Attached::Changes::DeleteOne) ||
+              current.attachment&.marked_for_destruction?
+            # no-op, drop the attachment, if any
+          elsif current.attached?
+            target.public_send("#{name}=", current.blob)
+          end
+        end
+      end
+
+      # Duplicates has_many_attached attachments from source to target.
+      # Public API: can be used directly for models that want to duplicate a
+      # specific attachment without including the concern, e.g.
+      #   DuplicatesAttachments::DupMany.new(:slides).apply(source, self)
+      class DupMany
+        attr_reader :name
+
+        def initialize(name)
+          @name = name.to_s
+        end
+
+        def apply(source, target)
+          current = source.public_send(name)
+          change  = source.attachment_changes[name]
+
+          # if attachments have changed, duplicate the change, otherwise attach the existing blobs
+          if change.is_a?(ActiveStorage::Attached::Changes::CreateMany)
+            target.public_send("#{name}=", change.attachables)
+          elsif change.is_a?(ActiveStorage::Attached::Changes::DeleteMany)
+            # no-op, drop the attachments, if any
+          elsif current.attached?
+            blobs = current.attachments.reject(&:marked_for_destruction?).map(&:blob)
+            target.public_send("#{name}=", blobs) if blobs.any?
+          end
+        end
+      end
+
+      DUPLICATORS = {
+        has_one_attached:  DupOne,
+        has_many_attached: DupMany,
+      }.freeze
+    end
+  end
+end

data/app/models/concerns/katalyst/content/duplicates_rich_text.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Content
+    # Copies ActionText rich text attributes when a record is duplicated,
+    # e.g. for copy-on-write. Unsaved changes on the source are carried over
+    # to the duplicate.
+    module DuplicatesRichText
+      extend ActiveSupport::Concern
+
+      def initialize_dup(source)
+        super
+
+        self.class.rich_text_association_names.each do |association|
+          DupRichText.new(association.to_s.delete_prefix("rich_text_")).apply(source, self)
+        end
+      end
+
+      # Duplicates a has_rich_text attribute from source to target.
+      # Public API: can be used directly for models that want to duplicate a
+      # specific rich text attribute without including the concern, e.g.
+      #   DuplicatesRichText::DupRichText.new(:subtitle).apply(source, self)
+      class DupRichText
+        attr_reader :name
+
+        def initialize(name)
+          @name = name.to_s
+        end
+
+        def apply(source, target)
+          rich_text = source.public_send("rich_text_#{name}")
+
+          # copy via body assignment so that custom attribute writers
+          # (e.g. Table#content=) are not re-run on the duplicate
+          target.public_send(name).body = rich_text.body if rich_text
+        end
+      end
+    end
+  end
+end

data/app/models/katalyst/content/content.rb

@@ -9,12 +9,6 @@ module Katalyst
 
       default_scope { with_rich_text_content }
 
-      def initialize_copy(source)
-        super
-
-        self.content = source.content&.body if source.content.is_a?(ActionText::RichText)
-      end
-
       def self.permitted_params
         super + %i[content]
       end

data/app/models/katalyst/content/figure.rb

@@ -12,17 +12,6 @@ module Katalyst
 
       default_scope { with_attached_image }
 
-      def initialize_dup(source)
-        super
-
-        # if image has changed, duplicate the change, otherwise attach the existing blob
-        if source.attachment_changes["image"]
-          self.image = source.attachment_changes["image"].attachable
-        elsif source.image.attached? && !source.image.marked_for_destruction?
-          image.attach(source.image.blob)
-        end
-      end
-
       def self.permitted_params
         super - %i[heading_style] + %i[image caption]
       end

data/app/models/katalyst/content/item.rb

@@ -4,6 +4,9 @@ module Katalyst
   module Content
     # STI base class for content items
     class Item < ApplicationRecord
+      include DuplicatesAssociations
+      include DuplicatesAttachments
+      include DuplicatesRichText
       include HasStyle
 
       def self.config

data/app/models/katalyst/content/table.rb

@@ -14,20 +14,10 @@ module Katalyst
 
       after_initialize :set_defaults
 
-      def initialize_copy(source)
-        super
-
-        content.body = source.content&.body if source.content.is_a?(ActionText::RichText)
-      end
-
       def self.permitted_params
         super + %i[content heading_rows heading_columns]
       end
 
-      def valid?(context = nil)
-        super
-      end
-
       def to_plain_text
         content.to_plain_text if visible?
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: katalyst-content
 version: !ruby/object:Gem::Version
-  version: 3.2.2
+  version: 3.3.0
 platform: ruby
 authors:
 - Katalyst Interactive
@@ -153,6 +153,9 @@ files:
 - app/javascript/content/editor/status_bar_controller.js
 - app/javascript/content/editor/table_controller.js
 - app/models/concerns/katalyst/content/container.rb
+- app/models/concerns/katalyst/content/duplicates_associations.rb
+- app/models/concerns/katalyst/content/duplicates_attachments.rb
+- app/models/concerns/katalyst/content/duplicates_rich_text.rb
 - app/models/concerns/katalyst/content/garbage_collection.rb
 - app/models/concerns/katalyst/content/has_style.rb
 - app/models/concerns/katalyst/content/has_tree.rb