katalyst-tables 2.1.2 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddd6b87989959fe3bea80d3d061984ace8fbaa918033ae6d40f1fb41fa752a4f
-  data.tar.gz: c1fcff810e0c6e76ae8ae8df7a92f26d0badd1601b6fd091748249eaeebdc262
+  metadata.gz: fc97f1a686a28e4542c65f076afde15d61523726efb4dcaa3586e6c945121c13
+  data.tar.gz: 10eee025b9e0daee5d3aeda7a78625e6491d91d02f99bf831092072845276185
 SHA512:
-  metadata.gz: 39a50df893890ed53a0d54acc7ab5d23a0292c9e98ec82b4e6286325713e115d718cfcdaf8caf6c0b2ce211ec20ea514eb53b5dc275dfe04bf253ee00d094aa5
-  data.tar.gz: 919db4197193d5c4d2be8ea6c15642ff309819757c32ae6cb99266412029e0d250156220584442d048b97a40bcc9c5cce7660d141ac9fb157d12d8468b6fd268
+  metadata.gz: 2a7e06d525551918f60e7b9a225f4ddb34bb3eeaeaecde37e817d0c61ade348f52e290235b21e84bedc72c92615f81e1226a10305242ff3e95e33fbb47a21878
+  data.tar.gz: 2d23b372c056506b054c02165e7191eb73d00f76df054e0d70eafbd88d6979126a3803c11bef29889f9095f644c7e40b30396da8d48580239978a7c9ee795019

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [2.2.0]
+
+- Add support for ordinal columns with batch updating
+  - See [[docs/ordinal.md]] for examples
+
 ## [2.1.0]
 
 - Add Collection model for building collections in a controller from params.

data/README.md

@@ -287,6 +287,12 @@ def index
 end
 ```
 
+## Extensions
+
+The following extensions are available:
+
+* [Orderable](docs/orderable.md) - adds bulk-update for 'ordinal' columns via dragging rows in the table.
+
 ## Customization
 
 A common pattern we use is to have a cell at the end of the table for actions. For example:
@@ -334,7 +340,7 @@ class ActionTableComponent < Katalyst::TableComponent
   config.body_row   = "ActionBodyRow"
   config.body_cell  = "ActionBodyCell"
   
-  def default_attributes
+  def default_html_attributes
     { class: "action-table" }
   end
 

data/app/assets/javascripts/controllers/tables/orderable/form_controller.js

@@ -0,0 +1,20 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class OrderableFormController extends Controller {
+  add(name, value) {
+    this.element.insertAdjacentHTML(
+      "beforeend",
+      `<input type="hidden" name="${name}" value="${value}" data-generated>`,
+    );
+  }
+
+  submit() {
+    this.element.requestSubmit();
+  }
+
+  clear() {
+    this.element
+      .querySelectorAll("input[data-generated]")
+      .forEach((input) => input.remove());
+  }
+}

data/app/assets/javascripts/controllers/tables/orderable/item_controller.js

@@ -0,0 +1,8 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class OrderableRowController extends Controller {
+  static values = {
+    name: String,
+    value: Number,
+  };
+}

data/app/assets/javascripts/controllers/tables/orderable/list_controller.js

@@ -0,0 +1,73 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class OrderableListController extends Controller {
+  static outlets = ["tables--orderable--item", "tables--orderable--form"];
+
+  dragstart(event) {
+    if (this.element !== event.target.parentElement) return;
+
+    const target = event.target;
+    event.dataTransfer.effectAllowed = "move";
+
+    // update element style after drag has begun
+    setTimeout(() => (target.dataset.dragging = ""));
+  }
+
+  dragover(event) {
+    if (!this.dragItem) return;
+
+    swap(this.dropTarget(event.target), this.dragItem);
+
+    event.preventDefault();
+    return true;
+  }
+
+  dragenter(event) {
+    event.preventDefault();
+  }
+
+  drop(event) {
+    if (!this.dragItem) return;
+
+    event.preventDefault();
+    delete this.dragItem.dataset.dragging;
+
+    this.update();
+  }
+
+  update() {
+    // clear any existing inputs to prevent duplicates
+    this.tablesOrderableFormOutlet.clear();
+
+    // insert any items that have changed position
+    this.tablesOrderableItemOutlets.forEach((item, index) => {
+      if (item.valueValue !== index) {
+        this.tablesOrderableFormOutlet.add(item.nameValue, index);
+      }
+    });
+
+    this.tablesOrderableFormOutlet.submit();
+  }
+
+  get dragItem() {
+    return this.element.querySelector("[data-dragging]");
+  }
+
+  dropTarget($e) {
+    while ($e && $e.parentElement !== this.element) {
+      $e = $e.parentElement;
+    }
+    return $e;
+  }
+}
+
+function swap(target, item) {
+  if (target && target !== item) {
+    const positionComparison = target.compareDocumentPosition(item);
+    if (positionComparison & Node.DOCUMENT_POSITION_FOLLOWING) {
+      target.insertAdjacentElement("beforebegin", item);
+    } else if (positionComparison & Node.DOCUMENT_POSITION_PRECEDING) {
+      target.insertAdjacentElement("afterend", item);
+    }
+  }
+}

data/app/assets/javascripts/controllers/tables/turbo_collection_controller.js

@@ -1,13 +1,14 @@
 import { Controller } from "@hotwired/stimulus";
+import { Turbo } from "@hotwired/turbo";
 
 export default class TurboCollectionController extends Controller {
   static values = {
     url: String,
     sort: String,
-  }
+  };
 
   urlValueChanged(url) {
-    window.history.replaceState({}, "", this.urlValue);
+    Turbo.navigator.history.replace(this.#url(url));
   }
 
   sortValueChanged(sort) {
@@ -19,4 +20,14 @@ export default class TurboCollectionController extends Controller {
   get #sortSelector() {
     return "input[name='sort']";
   }
+
+  #url(relativeUrl) {
+    const frame = this.element.closest("turbo-frame");
+
+    if (frame) {
+      return new URL(relativeUrl, frame.baseURI);
+    } else {
+      return new URL(relativeUrl, window.location.href);
+    }
+  }
 }

data/app/components/concerns/katalyst/tables/configurable_component.rb

@@ -14,18 +14,39 @@ module Katalyst
 
       class_methods do
         # Define a configurable sub-component.
-        def config_component(name, component_name: "#{name}_component", default: nil)
+        # Sub-components are cached on the table instance. We want to allow run
+        # time mixins for tables so that we can extend tables with cross-cutting
+        # concerns that affect multiple sub-components by including the concern
+        # into the top-level table class. We achieve this by subclassing the
+        # component as soon as it is created so that when a mixin is added to
+        # the table class, it can immediately retrieve and modify the
+        # sub-component class as well without needing to worry about affecting
+        # other tables.
+        def config_component(name, component_name: "#{name}_component", default: nil) # rubocop:disable Metrics/MethodLength
           config_accessor(name)
           config.public_send("#{name}=", default)
           define_method(component_name) do
-            instance_variable_get("@#{component_name}") if instance_variable_defined?("@#{component_name}")
+            return instance_variable_get("@#{component_name}") if instance_variable_defined?("@#{component_name}")
 
             klass     = config.public_send(name)
-            component = self.class.const_get(klass) if klass
+            component = klass ? self.class.const_get(klass) : nil
+
+            # subclass to allow table-specific extensions
+            if component
+              component = Class.new(component)
+              component.extend(HiddenSubcomponent)
+            end
+
             instance_variable_set("@#{component_name}", component) if component
           end
         end
       end
+
+      # View Component uses `name` to resolve the template path, so we need to
+      # hide the subclass from the template resolver.
+      module HiddenSubcomponent
+        delegate :name, to: :superclass
+      end
     end
   end
 end

data/app/components/concerns/katalyst/tables/has_html_attributes.rb

@@ -4,41 +4,57 @@ require "html_attributes_utils"
 
 module Katalyst
   module Tables
-    module HasHtmlAttributes # :nodoc:
+    # Adds HTML attributes to a component.
+    # Accepts HTML attributes from the constructor or via `html_attributes=`.
+    # These are merged with the default attributes defined in the component.
+    # Adds support for custom html attributes for other tags, e.g.:
+    #   define_html_attribute_methods :table_attributes, default: {}
+    #   tag.table(**table_attributes)
+    module HasHtmlAttributes
       extend ActiveSupport::Concern
 
       using HTMLAttributesUtils
 
-      DEFAULT_MERGEABLE_ATTRIBUTES = [
+      MERGEABLE_ATTRIBUTES = [
         *HTMLAttributesUtils::DEFAULT_MERGEABLE_ATTRIBUTES,
         %i[data controller],
-        %i[data action]
+        %i[data action],
       ].freeze
 
-      def initialize(**options)
-        super(**options.except(:id, :aria, :class, :data, :html))
-
-        self.html_attributes = options
+      refine Hash do
+        def merge_html(attributes)
+          deep_merge_html_attributes(attributes, mergeable_attributes: MERGEABLE_ATTRIBUTES)
+        end
       end
 
-      # Add HTML options to the current component.
-      # Public method for customizing components from within
-      def html_attributes=(options)
-        @html_attributes = options.slice(:id, :aria, :class, :data).merge(options.fetch(:html, {}))
-      end
+      class_methods do
+        using HasHtmlAttributes
+
+        def define_html_attribute_methods(name, default: {})
+          define_method("default_#{name}") { default }
+          private("default_#{name}")
 
-      # Backwards compatibility with tables 1.0
-      alias options html_attributes=
+          define_method(name) do
+            send("default_#{name}").merge_html(instance_variable_get("@#{name}") || {})
+          end
 
-      private
+          define_method("#{name}=") do |options|
+            instance_variable_set("@#{name}", options.slice(:id, :aria, :class, :data).merge(options.fetch(:html, {})))
+          end
+        end
+      end
+
+      included do
+        define_html_attribute_methods :html_attributes, default: {}
 
-      def html_attributes
-        default_attributes
-          .deep_merge_html_attributes(@html_attributes, mergeable_attributes: DEFAULT_MERGEABLE_ATTRIBUTES)
+        # Backwards compatibility with tables 1.0
+        alias_method :options, :html_attributes=
       end
 
-      def default_attributes
-        {}
+      def initialize(**options)
+        super(**options.except(:id, :aria, :class, :data, :html))
+
+        self.html_attributes = options
       end
     end
   end

data/app/components/concerns/katalyst/tables/orderable.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    # Adds drag and drop ordering to a table.
+    # See [documentation](/docs/orderable.md) for more details.
+    module Orderable
+      extend ActiveSupport::Concern
+
+      FORM_CONTROLLER = "tables--orderable--form"
+      ITEM_CONTROLLER = "tables--orderable--item"
+      LIST_CONTROLLER = "tables--orderable--list"
+
+      using HasHtmlAttributes
+
+      # Enhance a given table component class with orderable support.
+      # Supports extension via `included` and `extended` hooks.
+      def self.make_orderable(table_class)
+        # Add `orderable` columns to row components
+        table_class.header_row_component.include(HeaderRow)
+        table_class.body_row_component.include(BodyRow)
+
+        # Add `orderable` slot to table component
+        table_class.config_component :orderable, default: "FormComponent"
+        table_class.renders_one(:orderable, lambda do |**attrs|
+          orderable_component.new(table: self, **attrs)
+        end)
+      end
+
+      # Support for inclusion in a table component class
+      included do
+        Orderable.make_orderable(self)
+      end
+
+      # Support for extending a table component instance
+      def self.extended(table)
+        Orderable.make_orderable(table.class)
+      end
+
+      def tbody_attributes
+        return super unless orderable?
+
+        super.merge_html(
+          { data: { controller: LIST_CONTROLLER,
+                    action: <<~ACTIONS.squish,
+                      dragstart->#{LIST_CONTROLLER}#dragstart
+                      dragenter->#{LIST_CONTROLLER}#dragenter
+                      dragover->#{LIST_CONTROLLER}#dragover
+                      drop->#{LIST_CONTROLLER}#drop
+                    ACTIONS
+                    "#{LIST_CONTROLLER}-#{FORM_CONTROLLER}-outlet" => "##{orderable.id}",
+                    "#{LIST_CONTROLLER}-#{ITEM_CONTROLLER}-outlet" => "td.ordinal" } },
+        )
+      end
+
+      module HeaderRow # :nodoc:
+        def ordinal(attribute = :ordinal, **)
+          cell(attribute, class: "ordinal", label: "")
+        end
+      end
+
+      module BodyRow # :nodoc:
+        def ordinal(attribute = :ordinal, id: :id)
+          name  = @table.orderable.record_scope(@record, id, attribute)
+          value = @record.public_send(attribute)
+          cell(attribute, class: "ordinal", data: {
+                 controller: ITEM_CONTROLLER,
+                 "#{ITEM_CONTROLLER}-name-value" => name,
+                 "#{ITEM_CONTROLLER}-value-value" => value,
+               }) { t("katalyst.tables.orderable.value") }
+        end
+
+        def html_attributes
+          super.merge_html(
+            {
+              draggable: "true",
+            },
+          )
+        end
+      end
+
+      class FormComponent < ViewComponent::Base # :nodoc:
+        attr_reader :id, :url, :scope
+
+        def initialize(table:,
+                       url:,
+                       id: "#{table.id}-orderable-form",
+                       scope: "order[#{table.collection.model_name.plural}]")
+          super
+
+          @table = table
+          @id = id
+          @url = url
+          @scope = scope
+        end
+
+        def record_scope(record, id, attribute)
+          "#{scope}[#{record.public_send(id)}][#{attribute}]"
+        end
+
+        def call
+          form_with(id: id, url: url, method: :patch, data: { controller: FORM_CONTROLLER }) do |form|
+            form.button(hidden: "")
+          end
+        end
+
+        def inspect
+          "#<#{self.class.name} id: #{id.inspect}, url: #{url.inspect}, scope: #{scope.inspect}>"
+        end
+      end
+    end
+  end
+end

data/app/components/katalyst/table_component.html.erb

@@ -0,0 +1,13 @@
+<%= tag.table(**html_attributes) do %>
+  <%= render caption if caption? %>
+  <% if header? %>
+    <%= tag.thead(**thead_attributes) do %>
+      <%= header_row.render_in(view_context, &row_proc) %>
+    <% end %>
+  <% end %>
+  <%= tag.tbody(**tbody_attributes) do %>
+    <% collection.each do |record| %>
+      <%= body_row(record).render_in(view_context) { |r| row_proc.call(r, record) } %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/components/katalyst/table_component.rb

@@ -54,43 +54,24 @@ module Katalyst
       super(**html_attributes)
     end
 
-    def call
-      tag.table(**html_attributes) do
-        concat(caption)
-        concat(thead)
-        concat(tbody)
-      end
+    def caption?
+      @caption.present?
     end
 
     def caption
-      caption_component&.new(self)&.render_in(view_context) if @caption
+      caption_component&.new(self)
     end
 
-    def thead
-      return "".html_safe unless @header
-
-      tag.thead do
-        concat(render_header)
-      end
-    end
-
-    def tbody
-      tag.tbody do
-        collection.each do |record|
-          concat(render_row(record))
-        end
-      end
+    def header?
+      @header.present?
     end
 
-    def render_header
-      # extract the column's block from the slot and pass it to the cell for rendering
-      header_row_component.new(self, **@header_options).render_in(view_context, &row_proc)
+    def header_row
+      header_row_component.new(self, **@header_options)
     end
 
-    def render_row(record)
-      body_row_component.new(self, record).render_in(view_context) do |row|
-        row_proc.call(row, record)
-      end
+    def body_row(record)
+      body_row_component.new(self, record)
     end
 
     def sorting
@@ -98,5 +79,12 @@ module Katalyst
 
       collection.sorting if collection.respond_to?(:sorting)
     end
+
+    def inspect
+      "#<#{self.class.name} collection: #{collection.inspect}>"
+    end
+
+    define_html_attribute_methods(:thead_attributes)
+    define_html_attribute_methods(:tbody_attributes)
   end
 end

data/app/components/katalyst/tables/body_cell_component.rb

@@ -35,6 +35,10 @@ module Katalyst
       def value
         @record.public_send(@attribute)
       end
+
+      def inspect
+        "#<#{self.class.name} attribute: #{@attribute.inspect}, value: #{value.inspect}>"
+      end
     end
   end
 end

data/app/components/katalyst/tables/body_row_component.rb

@@ -35,6 +35,10 @@ module Katalyst
       def body?
         true
       end
+
+      def inspect
+        "#<#{self.class.name} record: #{record.inspect}>"
+      end
     end
   end
 end

data/app/components/katalyst/tables/empty_caption_component.rb

@@ -28,9 +28,13 @@ module Katalyst
         human.pluralize.downcase
       end
 
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
       private
 
-      def default_attributes
+      def default_html_attributes
         { align: "bottom" }
       end
     end

data/app/components/katalyst/tables/header_cell_component.rb

@@ -46,9 +46,13 @@ module Katalyst
         @attribute.to_s.humanize.capitalize
       end
 
+      def inspect
+        "#<#{self.class.name} attribute: #{@attribute.inspect}, value: #{value.inspect}>"
+      end
+
       private
 
-      def default_attributes
+      def default_html_attributes
         return {} unless sorting&.supports?(collection, @attribute)
 
         { data: { sort: sorting.status(@attribute) } }

data/app/components/katalyst/tables/header_row_component.rb

@@ -35,6 +35,10 @@ module Katalyst
       def body?
         false
       end
+
+      def inspect
+        "#<#{self.class.name} link_attributes: #{@link_attributes.inspect}>"
+      end
     end
   end
 end

data/app/components/katalyst/tables/pagy_nav_component.rb

@@ -23,6 +23,10 @@ module Katalyst
       def call
         pagy_nav(@pagy, **pagy_options).html_safe # rubocop:disable Rails/OutputSafety
       end
+
+      def inspect
+        "#<#{self.class.name} pagy: #{@pagy.inspect}>"
+      end
     end
   end
 end

data/app/components/katalyst/turbo/table_component.rb

@@ -23,13 +23,13 @@ module Katalyst
 
       private
 
-      def default_attributes
+      def default_html_attributes
         {
           data: {
-            controller: "tables--turbo-collection",
-            tables__turbo_collection_url_value: current_path,
-            tables__turbo_collection_sort_value: collection.sort
-          }
+            controller:                          "tables--turbo-collection",
+            tables__turbo_collection_url_value:  current_path,
+            tables__turbo_collection_sort_value: collection.sort,
+          },
         }
       end
 

data/config/importmap.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true
+pin "@hotwired/turbo", to: "turbo.min.js", preload: true
 
 pin_all_from Katalyst::Tables::Engine.root.join("app/assets/javascripts"),
              # preload in tests so that we don't start clicking before controllers load

data/config/locales/tables.en.yml

@@ -0,0 +1,6 @@
+en:
+  katalyst:
+    tables:
+      orderable:
+        value:
+          "⠿"

data/lib/katalyst/tables/backend.rb

@@ -22,9 +22,9 @@ module Katalyst
         column, direction = params[:sort]&.split(" ")
         direction         = "asc" unless SortForm::DIRECTIONS.include?(direction)
 
-        SortForm.new(column: column,
+        SortForm.new(column:    column,
                      direction: direction)
-                .apply(collection)
+          .apply(collection)
       end
 
       def self_referred?

data/lib/katalyst/tables/version.rb

@@ -2,6 +2,6 @@
 
 module Katalyst
   module Tables
-    VERSION = "2.1.2"
+    VERSION = "2.2.0"
   end
 end

data/lib/katalyst/tables.rb

@@ -7,7 +7,7 @@ require_relative "tables/engine"
 require_relative "tables/frontend"
 require_relative "tables/version"
 
-require_relative "tables/engine" if Object.const_defined?("Rails")
+require_relative "tables/engine" if Object.const_defined?(:Rails)
 
 module Katalyst
   module Tables

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: katalyst-tables
 version: !ruby/object:Gem::Version
-  version: 2.1.2
+  version: 2.2.0
 platform: ruby
 authors:
 - Katalyst Interactive
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-27 00:00:00.000000000 Z
+date: 2023-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: html-attributes-utils
@@ -50,12 +50,17 @@ files:
 - LICENSE.txt
 - README.md
 - app/assets/config/katalyst-tables.js
+- app/assets/javascripts/controllers/tables/orderable/form_controller.js
+- app/assets/javascripts/controllers/tables/orderable/item_controller.js
+- app/assets/javascripts/controllers/tables/orderable/list_controller.js
 - app/assets/javascripts/controllers/tables/turbo_collection_controller.js
 - app/components/concerns/katalyst/tables/configurable_component.rb
 - app/components/concerns/katalyst/tables/has_html_attributes.rb
 - app/components/concerns/katalyst/tables/has_table_content.rb
+- app/components/concerns/katalyst/tables/orderable.rb
 - app/components/concerns/katalyst/tables/sortable.rb
 - app/components/concerns/katalyst/tables/turbo_replaceable.rb
+- app/components/katalyst/table_component.html.erb
 - app/components/katalyst/table_component.rb
 - app/components/katalyst/tables/body_cell_component.rb
 - app/components/katalyst/tables/body_row_component.rb
@@ -72,6 +77,7 @@ files:
 - app/models/concerns/katalyst/tables/collection/sorting.rb
 - app/models/katalyst/tables/collection.rb
 - config/importmap.rb
+- config/locales/tables.en.yml
 - lib/katalyst/tables.rb
 - lib/katalyst/tables/backend.rb
 - lib/katalyst/tables/backend/sort_form.rb