katalyst-tables 3.0.0 → 3.2.0

data/app/components/katalyst/tables/filter/modal_component.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Filter
+      class ModalComponent < ViewComponent::Base
+        include Katalyst::HtmlAttributes
+        include Katalyst::Tables::Frontend
+
+        DEFAULT_ATTRIBUTES = %w[page sort search query].freeze
+
+        renders_one :footer
+
+        attr_reader :collection, :url
+
+        def initialize(collection:, **)
+          super(**)
+
+          @collection = collection
+        end
+
+        private
+
+        def default_html_attributes
+          {
+            class: "filter-keys-modal",
+            data:  {
+              tables__filter__modal_target: "modal",
+            },
+          }
+        end
+
+        def attributes
+          collection.class.attribute_types.except(*DEFAULT_ATTRIBUTES)
+        end
+
+        def values_for(key, attribute)
+          values_method = "#{key.parameterize.underscore}_values"
+          if attribute.type == :boolean
+            render_options(true, false)
+          elsif collection.model.defined_enums.has_key?(key)
+            render_array(*collection.model.defined_enums[key].keys)
+          elsif collection.respond_to?(values_method)
+            if collection.class.enum_attribute?(key)
+              render_array(*collection.public_send(values_method))
+            else
+              render_options(*collection.public_send(values_method))
+            end
+          end
+        end
+
+        def render_option(value)
+          "<code>#{value}</code>".html_safe # rubocop:disable Rails/OutputSafety
+        end
+
+        def render_options(*values)
+          safe_join(values.map { |value| render_option(value) }, ", ")
+        end
+
+        def render_array(*values)
+          safe_join(["[", render_options(*values), "]"])
+        end
+      end
+    end
+  end
+end

data/app/components/katalyst/tables/filter_component.html.erb

@@ -0,0 +1,20 @@
+<%= tag.div(**html_attributes) do %>
+  <% if content? %>
+    <%= content %>
+  <% else %>
+    <%= form do |form| %>
+      <%= form.text_field(
+            :query,
+            type:         :search,
+            size:         :full,
+            label:        nil,
+            autocomplete: "off",
+            **input_attributes,
+          ) %>
+
+      <%= form.submit("Apply") %>
+    <% end %>
+  <% end %>
+
+  <%= modal %>
+<% end %>

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    # A component for rendering a data driven filter for a collection.
+    #   <%= Katalyst::Tables::FilterComponent.new(collection: @people, url: peoples_path) %>
+    #
+    # By default, the component will render a form containing a single text field. Interacting with the
+    # text field will display a dropdown outlining all available keys and values to be filtered on.
+    #
+    # You can override how the form and input displays by passing in content to the component.
+    # The component provides a helper function `form`
+    # to ensure the correct attributes and default form fields are collected.
+    # You can pass additional options to the `form` method to modify it.
+    #
+    #   <%= Katalyst::Tables::FilterComponent.new(collection: @people, url: peoples_path) do |filter| %>
+    #     <%= filter.form(builder: GOVUKFormBuilder) do |form| %>
+    #         <%= form.govuk_text_field :query %>
+    #         <%= form.govuk_submit "Apply" %>
+    #     <% end %>
+    #   <% end %>
+    #
+    #
+    # Additionally the component allows for access to the dropdown that displays when interacting with the input.
+    # The dropdown supports additional "footer" content to be added.
+    #
+    #   <%= Katalyst::Tables::FilterComponent.new(collection: @people, url: peoples_path) do |filter| %>
+    #     <% filter.with_modal(collection:) do |modal| %>
+    #         <% modal.with_footer do %>
+    #           <%= link_to "Docs", docs_path %>
+    #         <% end %>
+    #     <% end %>
+    #   <% end %>
+    #
+    class FilterComponent < ViewComponent::Base
+      include Katalyst::HtmlAttributes
+      include Katalyst::Tables::Frontend
+
+      renders_one :modal, Katalyst::Tables::Filter::ModalComponent
+
+      define_html_attribute_methods :input_attributes
+
+      attr_reader :collection, :url
+
+      def initialize(collection:, url:, **)
+        super(**)
+
+        @collection = collection
+        @url        = url
+      end
+
+      def before_render
+        with_modal(collection:) unless modal?
+      end
+
+      def form(url: @url, **options, &)
+        form_with(model:  collection,
+                  url:,
+                  method: :get,
+                  **options) do |form|
+          concat(form.hidden_field(:sort))
+
+          yield form if block_given?
+        end
+      end
+
+      private
+
+      def default_html_attributes
+        {
+          data: {
+            controller: "tables--filter--modal",
+            action:     <<~ACTIONS.gsub(/\s+/, " "),
+              click@window->tables--filter--modal#close
+              click->tables--filter--modal#open:stop
+              keydown.esc->tables--filter--modal#close
+            ACTIONS
+          },
+        }
+      end
+
+      def default_input_attributes
+        {
+          data: {
+            action: "focus->tables--filter--modal#open",
+          },
+        }
+      end
+    end
+  end
+end

data/app/components/katalyst/tables/summary/body_component.html.erb

@@ -0,0 +1,3 @@
+<% cells.each do |cell| %>
+  <%= cell %>
+<% end %>

data/app/components/katalyst/tables/summary/body_component.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Summary
+      class BodyComponent < Katalyst::Tables::BodyRowComponent
+      end
+    end
+  end
+end

data/app/components/katalyst/tables/summary/header_component.html.erb

@@ -0,0 +1,3 @@
+<% cells.each do |cell| %>
+  <%= cell %>
+<% end %>

data/app/components/katalyst/tables/summary/header_component.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Summary
+      class HeaderComponent < Katalyst::Tables::HeaderRowComponent
+      end
+    end
+  end
+end

data/app/components/katalyst/tables/summary/row_component.html.erb

@@ -0,0 +1,4 @@
+<tr>
+  <%= header %>
+  <%= body %>
+</tr>

data/app/components/katalyst/tables/summary/row_component.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Summary
+      class RowComponent < ViewComponent::Base
+        renders_one :header, Summary::HeaderComponent
+        renders_one :body, Summary::BodyComponent
+      end
+    end
+  end
+end

data/app/controllers/concerns/katalyst/tables/backend.rb

@@ -8,6 +8,7 @@ module Katalyst
 
       included do
         class_attribute :_default_table_component, instance_accessor: false
+        class_attribute :_default_summary_table_component, instance_accessor: false
       end
 
       class_methods do
@@ -18,12 +19,26 @@ module Katalyst
         def default_table_component(component)
           self._default_table_component = component
         end
+
+        # Set the summary table component to be used as the default for all
+        # summary tables in the views rendered by this controller and its
+        # subclasses.
+        #
+        # @param component [Class] the summary table component class to use
+        def default_summary_table_component(component)
+          self._default_summary_table_component = component
+        end
       end
 
       # Default table component for this controller
       def default_table_component
         self.class._default_table_component
       end
+
+      # Default summary table component for this controller
+      def default_summary_table_component
+        self.class._default_summary_table_component
+      end
     end
   end
 end

data/app/helpers/katalyst/tables/frontend.rb

@@ -55,12 +55,39 @@ module Katalyst
         render(Selectable::FormComponent.new(collection:, id:, primary_key:), &)
       end
 
+      # Construct a new summary table component.
+      #
+      # @param model [ActiveRecord::Base] subject for the table
+      #
+      # Blocks will receive the table in row-rendering mode (with row and record defined):
+      # @yieldparam [Katalyst::TableComponent] the table component to render rows
+      # @yieldparam [nil, Object] nil for the header column, or the given model for the value column
+      def summary_table_with(model:, **, &)
+        component ||= default_summary_table_component_class
+        component = component.new(model:, **)
+
+        render(component, &)
+      end
+
+      # Construct a new filter.
+      #
+      # @param collection [Katalyst::Tables::Collection::Core] the collection to render
+      # @param url [String] the url to submit the form to (e.g. <resources>_path)
+      def filter_with(collection:, url: url_for(action: :index), &)
+        render(FilterComponent.new(collection:, url:), &)
+      end
+
       private
 
       def default_table_component_class
         component = controller.try(:default_table_component) || TableComponent
         component.respond_to?(:constantize) ? component.constantize : component
       end
+
+      def default_summary_table_component_class
+        component = controller.try(:default_summary_table_component) || SummaryTableComponent
+        component.respond_to?(:constantize) ? component.constantize : component
+      end
     end
   end
 end

data/app/javascript/tables/application.js

@@ -3,6 +3,7 @@ import OrderableListController from "./orderable/list_controller";
 import OrderableFormController from "./orderable/form_controller";
 import SelectionFormController from "./selection/form_controller";
 import SelectionItemController from "./selection/item_controller";
+import FilterModalController from "./filter/modal_controller";
 
 const Definitions = [
   {
@@ -25,6 +26,10 @@ const Definitions = [
     identifier: "tables--selection--item",
     controllerConstructor: SelectionItemController,
   },
+  {
+    identifier: "tables--filter--modal",
+    controllerConstructor: FilterModalController,
+  },
 ];
 
 export { Definitions as default };

data/app/javascript/tables/filter/modal_controller.js

@@ -0,0 +1,13 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class FilterModalController extends Controller {
+  static targets = ["modal"];
+
+  close(e) {
+    delete this.modalTarget.dataset.open;
+  }
+
+  open(e) {
+    this.modalTarget.dataset.open = "true";
+  }
+}

data/app/models/concerns/katalyst/tables/collection/core.rb

@@ -25,6 +25,10 @@ module Katalyst
                    end
             end
           end
+
+          def enum_attribute?(key)
+            _default_attributes[key].value.is_a?(::Array)
+          end
         end
 
         included do
@@ -39,11 +43,21 @@ module Katalyst
           clear_changes_information
         end
 
+        # Collections are filtered when any parameters have changed from their defaults.
+        def filtered?
+          filters.any?
+        end
+
         # Collections that do not include Sorting are never sortable.
         def sortable?
           false
         end
 
+        # Collections that do not include Query are never searchable.
+        def searchable?
+          false
+        end
+
         def apply(items)
           @items = items
           reducers.build do |_|
@@ -52,6 +66,22 @@ module Katalyst
           end.call(self)
           self
         end
+
+        def filter
+          # no-op by default
+        end
+
+        def filters
+          changes.except("sort", "page", "query").transform_values(&:second)
+        end
+
+        def model
+          if items < ActiveRecord::Base
+            items
+          else
+            items.model
+          end
+        end
       end
     end
   end

data/app/models/concerns/katalyst/tables/collection/filtering.rb

@@ -3,19 +3,90 @@
 module Katalyst
   module Tables
     module Collection
-      using HasParams
+      module Filtering
+        extend ActiveSupport::Concern
 
-      module Filtering # :nodoc:
-        def filter
-          # no-op by default
-        end
+        DEFAULT_ATTRIBUTES = %w[sort page query].freeze
 
-        def filtered?
-          filters.any?
+        included do
+          use(Filter)
         end
 
-        def filters
-          changed_attributes.except("sort", "page")
+        class Filter
+          include ActiveRecord::Sanitization::ClassMethods
+
+          def initialize(app)
+            @app = app
+          end
+
+          def call(collection)
+            collection.class._default_attributes.each_value do |attribute|
+              key = attribute.name
+
+              next if DEFAULT_ATTRIBUTES.include?(key)
+
+              value = collection.attributes[key]
+
+              filter_attribute(collection, key, value, attribute.type.type)
+            end
+
+            @app.call(collection)
+          end
+
+          def filter_attribute(collection, key, value, type)
+            if key == "search"
+              search(collection, value)
+            elsif type == :string
+              filter_matches(collection, key, value)
+            elsif type == :boolean
+              filter_eq(collection, key, value) unless value.nil?
+            elsif value.present?
+              filter_eq(collection, key, value)
+            end
+          end
+
+          def search(collection, search)
+            return if search.blank? || !collection.searchable?
+
+            collection.items = collection.items.public_send(collection.config.search_scope, search)
+          end
+
+          def filter_matches(collection, key, value)
+            return if value.nil?
+
+            model, column = join_key(collection, key)
+            arel_column = model.arel_table[column]
+
+            collection.items = collection.items.where(arel_column.matches("%#{sanitize_sql_like(value)}%"))
+          end
+
+          def filter_eq(collection, key, value)
+            model, column = join_key(collection, key)
+
+            condition = if model.attribute_types.has_key?(column)
+                          model.where(column => value)
+                        else
+                          model.public_send(column, value)
+                        end
+
+            collection.items = collection.items.merge(condition)
+          end
+
+          private
+
+          def join_key(collection, key)
+            if key.include?(".")
+              table, column = key.split(".")
+              collection.items = collection.items.joins(table.to_sym)
+              [collection.items.reflections[table].klass, column]
+            else
+              [collection.items.model, key]
+            end
+          end
+
+          def column_for(key)
+            key.include?(".") ? key.split(".").last : key
+          end
         end
       end
     end

data/app/models/concerns/katalyst/tables/collection/pagination.rb

@@ -24,8 +24,8 @@ module Katalyst
           config_accessor :paginate
         end
 
-        def initialize(paginate: config.paginate, **options)
-          super(**options)
+        def initialize(paginate: config.paginate, **)
+          super(**)
 
           @paginate = paginate.freeze
         end

data/app/models/concerns/katalyst/tables/collection/query/array_value_parser.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Query
+        class ArrayValueParser < ValueParser
+          # @param query [StringScanner]
+          def parse(query)
+            @query = query
+
+            skip_whitespace
+
+            if query.scan(/#{'\['}/)
+              take_values
+            else
+              take_value
+            end
+          end
+
+          def take_values
+            until query.eos?
+              skip_whitespace
+              break unless take_quoted_value || take_unquoted_value
+
+              skip_whitespace
+              break unless take_delimiter
+            end
+
+            skip_whitespace
+            take_end_of_list
+          end
+
+          def take_value
+            take_quoted_value || take_unquoted_value
+          end
+
+          def take_delimiter
+            query.scan(/#{','}/)
+          end
+
+          def take_end_of_list
+            query.scan(/#{']'}/)
+          end
+
+          def value=(value)
+            return if @attribute.type_cast(value).nil? # undefined attribute
+
+            current = @collection.attributes[@attribute.name]
+            @collection.assign_attributes(@attribute.name => current + [value])
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/katalyst/tables/collection/query/parser.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Query
+        class Parser # :nodoc:
+          # query [StringScanner]
+          attr_accessor :query
+          attr_reader :collection, :untagged
+
+          def initialize(collection)
+            @collection = collection
+            @untagged   = []
+          end
+
+          # @param query [String]
+          def parse(query)
+            @query = StringScanner.new(query)
+
+            until @query.eos?
+              skip_whitespace
+
+              # break to ensure we don't loop indefinitely on bad input
+              break unless take_tagged || take_untagged
+            end
+
+            self
+          end
+
+          private
+
+          def skip_whitespace
+            query.scan(/\s+/)
+          end
+
+          def take_tagged
+            return unless query.scan(/(\w+(\.\w+)?):/)
+
+            key, = query.values_at(1)
+            parser_for(key).parse(query)
+          end
+
+          def take_untagged
+            return unless query.scan(/\S+/)
+
+            untagged << query.matched
+
+            untagged
+          end
+
+          def parser_for(key)
+            attribute = collection.class._default_attributes[key]
+
+            if collection.class.enum_attribute?(key)
+              ArrayValueParser.new(collection:, attribute:)
+            else
+              SingleValueParser.new(collection:, attribute:)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/katalyst/tables/collection/query/single_value_parser.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Query
+        class SingleValueParser < ValueParser
+          # @param query [StringScanner]
+          def parse(query)
+            @query = query
+
+            take_quoted_value || take_unquoted_value
+          end
+
+          def value=(value)
+            return if @attribute.type_cast(value).nil? # undefined attribute
+
+            @collection.assign_attributes(@attribute.name => value)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/katalyst/tables/collection/query/value_parser.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Query
+        class ValueParser
+          attr_accessor :query
+
+          def initialize(collection:, attribute:)
+            @collection = collection
+            @attribute  = attribute
+          end
+
+          def take_quoted_value
+            return unless query.scan(/"([^"]*)"/)
+
+            self.value, = query.values_at(1)
+          end
+
+          def take_unquoted_value
+            return unless query.scan(/([^" \],]*)/)
+
+            self.value, = query.values_at(1)
+          end
+
+          def skip_whitespace
+            query.scan(/\s+/)
+          end
+        end
+      end
+    end
+  end
+end