katalyst-tables 3.1.0 → 3.3.0

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/helpers/katalyst/tables/frontend.rb

@@ -69,6 +69,14 @@ module Katalyst
         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

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,24 @@ module Katalyst
                    end
             end
           end
+
+          using Type::Helpers::Extensions
+
+          def attribute(name, type = nil, default: (no_default = true), **)
+            type = type.is_a?(Symbol) ? resolve_type_name(type, **) : type || Type::Value.new
+
+            default = type.default_value if no_default
+
+            default.nil? && no_default ? super(name, type, **) : super
+          end
+
+          private
+
+          # @override ActiveModel::AttributeRegistration::ClassMethods#resolve_type_name()
+          def resolve_type_name(name, **)
+            # note, this is Katalyst::Tables::Collection::Type, not ActiveModel::Type
+            Type.lookup(name, **)
+          end
         end
 
         included do
@@ -39,11 +57,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 +80,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,27 @@
 module Katalyst
   module Tables
     module Collection
-      using HasParams
+      module Filtering
+        extend ActiveSupport::Concern
 
-      module Filtering # :nodoc:
-        def filter
-          # no-op by default
+        included do
+          use(Filter)
         end
 
-        def filtered?
-          filters.any?
-        end
+        class Filter
+          include ActiveRecord::Sanitization::ClassMethods
+
+          def initialize(app)
+            @app = app
+          end
+
+          def call(collection)
+            collection.instance_variable_get(:@attributes).each_value do |attribute|
+              collection.items = attribute.type.filter(collection.items, attribute)
+            end
 
-        def filters
-          changed_attributes.except("sort", "page")
+            @app.call(collection)
+          end
         end
       end
     end

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

@@ -19,7 +19,7 @@ module Katalyst
         included do
           attr_accessor :pagination
 
-          attribute :page, :integer, default: 1
+          attribute :page, :integer, default: 1, filter: false
 
           config_accessor :paginate
         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,73 @@
+# 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
+
+            if untagged.any? && (search = collection.class.search_attribute)
+              collection.assign_attributes(search => untagged.join(" "))
+            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)
+            skip_whitespace
+
+            parser_for(key).parse(query)
+          end
+
+          def take_untagged
+            return unless query.scan(/\S+/)
+
+            untagged << query.matched
+
+            untagged
+          end
+
+          using Type::Helpers::Extensions
+
+          def parser_for(key)
+            attribute = collection.class._default_attributes[key]
+
+            if attribute.type.multiple? || attribute.value.is_a?(::Array)
+              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

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Query # :nodoc:
+        extend ActiveSupport::Concern
+
+        include Filtering
+
+        class_methods do
+          def search_attribute
+            _default_attributes.each_value do |attribute|
+              return attribute.name if attribute.type.type == :search
+            end
+          end
+        end
+
+        included do
+          attribute :query, :query, default: ""
+
+          # Note: this is defined inline so that we can overwrite query=
+          def query=(value)
+            query = super
+
+            Parser.new(self).parse(query)
+
+            query
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -40,7 +40,7 @@ module Katalyst
         using SortParams
 
         included do
-          attribute :sort, :string
+          attribute :sort, :string, filter: false
 
           attr_reader :default_sort
         end

data/app/models/katalyst/tables/collection/array.rb

@@ -6,7 +6,6 @@ module Katalyst
       # Entry point for creating a collection from an array for use with table components.
       class Array
         include Core
-        include Filtering
 
         def self.with_params(params)
           new.with_params(params)

data/app/models/katalyst/tables/collection/base.rb

@@ -23,7 +23,6 @@ module Katalyst
       # ````
       class Base
         include Core
-        include Filtering
         include Pagination
         include Sorting
 
@@ -34,10 +33,6 @@ module Katalyst
           new.with_params(params)
         end
 
-        def model
-          items.model
-        end
-
         def model_name
           @model_name ||= items.model_name.dup.tap do |name|
             name.param_key = ""

data/app/models/katalyst/tables/collection/filter.rb

@@ -23,7 +23,6 @@ module Katalyst
       # ````
       class Filter
         include Core
-        include Filtering
         include Pagination
         include Sorting
 

data/app/models/katalyst/tables/collection/type/boolean.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Type
+        class Boolean < Value
+          include Helpers::Delegate
+          include Helpers::Multiple
+
+          def initialize(**)
+            super(**, delegate: ActiveModel::Type::Boolean)
+          end
+
+          def filter?(attribute, value)
+            (!value.nil? && !value.eql?([])) || attribute.came_from_user?
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/katalyst/tables/collection/type/date.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Type
+        class Date < Value
+          def type
+            :date
+          end
+
+          def serialize(value)
+            if value.is_a?(Date)
+              value.to_fs(:db)
+            elsif value.is_a?(Range)
+              if value.begin.nil?
+                "<#{value.end.to_fs(:db)}"
+              elsif value.end.nil?
+                ">#{value.begin.to_fs(:db)}"
+              else
+                "#{value.begin.to_fs(:db)}..#{value.end.to_fs(:db)}"
+              end
+            else
+              value.to_s
+            end
+          end
+
+          private
+
+          ISO_DATE = /\A(\d{4})-(\d\d)-(\d\d)\z/
+          LOWER_BOUND = /\A>(\d{4})-(\d\d)-(\d\d)\z/
+          UPPER_BOUND = /\A<(\d{4})-(\d\d)-(\d\d)\z/
+          BOUNDED = /\A(\d{4})-(\d\d)-(\d\d)\.\.(\d{4})-(\d\d)-(\d\d)\z/
+
+          def cast_value(value)
+            return value unless value.is_a?(::String)
+
+            if value =~ ISO_DATE
+              new_date($1.to_i, $2.to_i, $3.to_i)
+            elsif value =~ LOWER_BOUND
+              (new_date($1.to_i, $2.to_i, $3.to_i)..)
+            elsif value =~ UPPER_BOUND
+              (..new_date($1.to_i, $2.to_i, $3.to_i))
+            elsif value =~ BOUNDED
+              (new_date($1.to_i, $2.to_i, $3.to_i)..new_date($4.to_i, $5.to_i, $6.to_i))
+            end
+          end
+
+          def new_date(year, mon, mday)
+            return nil if year.nil? || (year.zero? && mon.zero? && mday.zero?)
+
+            ::Date.new(year, mon, mday)
+          rescue ArgumentError, TypeError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/katalyst/tables/collection/type/enum.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Type
+        class Enum < Value
+          include Helpers::Multiple
+
+          def initialize(multiple: true, **)
+            super
+          end
+
+          def type
+            :enum
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/katalyst/tables/collection/type/float.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Type
+        class Float < Value
+          include Helpers::Delegate
+          include Helpers::Multiple
+
+          def initialize(**)
+            super(**, delegate: ActiveModel::Type::Float)
+          end
+
+          def serialize(value)
+            if value.is_a?(Range)
+              if value.begin.nil?
+                "<#{super(value.end)}"
+              elsif value.end.nil?
+                ">#{super(value.begin)}"
+              else
+                "#{super(value.begin)}..#{super(value.end)}"
+              end
+            else
+              super
+            end
+          end
+
+          private
+
+          FLOAT = /(-?\d+(?:\.\d+)?)/
+          SINGLE_VALUE = /\A#{FLOAT}\z/
+          LOWER_BOUND = /\A>#{FLOAT}\z/
+          UPPER_BOUND = /\A<#{FLOAT}\z/
+          BOUNDED = /\A#{FLOAT}\.\.#{FLOAT}\z/
+
+          def cast_value(value)
+            case value
+            when ::Range, ::Integer
+              value
+            when SINGLE_VALUE
+              super($1)
+            when LOWER_BOUND
+              ((super($1))..)
+            when UPPER_BOUND
+              (..(super($1)))
+            when BOUNDED
+              ((super($1))..(super($2)))
+            else
+              super
+            end
+          end
+        end
+      end
+    end
+  end
+end