katalyst-tables 3.3.0 → 3.3.2

data/app/assets/stylesheets/katalyst/tables/typed-columns/_date.scss

@@ -1,4 +1,4 @@
 // where psuedo selector has a specificity of 0 so it can be easily overwritten with simple selectors
 :where(th.type-date, td.type-date) {
-  width: var(--width-medium);
+  width: var(--width-small);
 }

data/app/assets/stylesheets/katalyst/tables/typed-columns/_datetime.scss

@@ -1,4 +1,4 @@
 // where psuedo selector has a specificity of 0 so it can be easily overwritten with simple selectors
-:where(th.type-datetime, td.type-date) {
+:where(th.type-datetime, td.type-datetime) {
   width: var(--width-medium);
 }

data/app/components/katalyst/table_component.rb

@@ -239,9 +239,20 @@ module Katalyst
 
     # Generates a column from numeric values formatted appropriately.
     #
+    # Supports Rails' built in number formatters, i.e.
+    #  * +phone+: ActiveSupport::NumberHelper#number_to_phone
+    #  * +currency+: ActiveSupport::NumberHelper#number_to_currency
+    #  * +percentage+: ActiveSupport::NumberHelper#number_to_percentage
+    #  * +delimited+: ActiveSupport::NumberHelper#number_to_delimited
+    #  * +rounded+: ActiveSupport::NumberHelper#number_to_rounded
+    #  * +human_size+: ActiveSupport::NumberHelper#number_to_human_size
+    #  * +human+: ActiveSupport::NumberHelper#number_to_human
+    #
     # @param column [Symbol] the column's name, called as a method on the record
     # @param label [String|nil] the label to use for the column header
     # @param heading [boolean] if true, data cells will use `th` tags
+    # @param format [String|Symbol] Rails number_to_X format option, defaults to +delimited+
+    # @param options [Hash] options to be passed to `number_to_<format>`
     # @param ** [Hash] HTML attributes to be added to column cells
     # @param & [Proc] optional block to alter the cell content
     #
@@ -252,9 +263,9 @@ module Katalyst
     #
     # @example Render the number of comments on a post
     #   <% row.number :comment_count %> # => <td>0</td>
-    def number(column, label: nil, heading: false, **, &)
+    def number(column, label: nil, heading: false, format: :delimited, options: {}, **, &)
       with_cell(Tables::Cells::NumberComponent.new(
-                  collection:, row:, column:, record:, label:, heading:, **,
+                  collection:, row:, column:, record:, label:, heading:, format:, options:, **,
                 ), &)
     end
 

data/app/components/katalyst/tables/cells/currency_component.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require "bigdecimal/util"
+
 module Katalyst
   module Tables
     module Cells
       # Formats the value as a money value
       #
-      # The value is expected to be in cents.
+      # The value is assumed to be cents if integer, or dollars if float or
+      # decimal. Also supports RubyMoney type if defined.
+      #
       # Adds a class to the cell to allow for custom styling
       class CurrencyComponent < CellComponent
         def initialize(options:, **)
@@ -15,7 +19,22 @@ module Katalyst
         end
 
         def rendered_value
-          value.present? ? number_to_currency(value / 100.0, @options) : ""
+          format(value)
+        end
+
+        def format(value)
+          value.present? ? number_to_currency(value, @options) : ""
+        end
+
+        def value
+          case (v = super)
+          when nil
+            nil
+          when Integer
+            (super.to_d / BigDecimal("100"))
+          else
+            (v.to_d rescue nil) # rubocop:disable Style/RescueModifier
+          end
         end
 
         private

data/app/components/katalyst/tables/cells/number_component.rb

@@ -7,8 +7,38 @@ module Katalyst
       #
       # Adds a class to the cell to allow for custom styling
       class NumberComponent < CellComponent
+        include ActiveSupport::NumberHelper
+
+        def initialize(format:, options:, **)
+          super(**)
+
+          @format = format
+          @options = options
+        end
+
+        def format(value)
+          case @format
+          when :phone
+            number_to_phone(value, @options)
+          when :currency
+            number_to_currency(value, @options)
+          when :percentage
+            number_to_percentage(value, @options)
+          when :delimited
+            number_to_delimited(value, @options)
+          when :rounded
+            number_to_rounded(value, @options)
+          when :human_size
+            number_to_human_size(value, @options)
+          when :human
+            number_to_human(value, @options)
+          else
+            raise ArgumentError, "Unsupported format #{@format}"
+          end
+        end
+
         def rendered_value
-          value.present? ? number_to_human(value) : ""
+          value.present? ? format(value) : ""
         end
 
         private

data/app/components/katalyst/tables/query/input_component.html.erb

@@ -0,0 +1,12 @@
+<div class="query-input" data-controller="tables--query-input" data-turbo-permanent>
+  <%= form.label name, "Search", hidden: "" %>
+  <%= form.text_field(
+        name,
+        type:         :search,
+        autocomplete: "off",
+        **html_attributes,
+      ) %>
+  <div aria-hidden="true" class="highlight" data-tables--query-input-target="highlight"></div>
+  <%= form.hidden_field(:p) %>
+  <%= form.button("Apply", type: :submit, name: nil, tabindex: -1) %>
+</div>

data/app/components/katalyst/tables/query/input_component.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Query
+      class InputComponent < ViewComponent::Base
+        include Katalyst::HtmlAttributes
+
+        attr_reader :form
+
+        def initialize(form:, **)
+          super(**)
+
+          @form = form
+        end
+
+        def name
+          query_attribute || raise(ArgumentError, "No query attribute. " \
+                                                  "Does your collection include Katalyst::Tables::Collection::Query?")
+        end
+
+        def collection
+          form.object
+        end
+
+        def default_html_attributes
+          {
+            data: {
+              action:                     %w[
+                input->tables--query-input#update
+                keyup.enter->tables--query#closeModal
+              ],
+              tables__query_input_target: "input",
+            },
+          }
+        end
+
+        private
+
+        def query_attribute
+          collection.class.attribute_types.detect { |_, a| a.type == :query }&.first
+        end
+      end
+    end
+  end
+end

data/app/components/katalyst/tables/query/modal_component.html.erb

@@ -0,0 +1,33 @@
+<%= tag.section(**html_attributes) do %>
+  <% if collection.errors.any? %>
+    <header>
+      <% collection.errors.each do |error| %>
+        <% next unless error.type == :unknown %>
+        <div class="error">Sorry, we don&rsquo;t support the <code><%= error.attribute %></code> filter.</div>
+      <% end %>
+    </header>
+  <% end %>
+  <div class="content">
+    <% if show_values? %>
+      <h4>Possible values for <code><%= current_key %>:</code></h4>
+      <ul>
+        <% values_for(current_key).each do |value| %>
+          <li><code><%= format_value(value) %></code></li>
+        <% end %>
+      </ul>
+    <% else %>
+      <h4>Available filters:</h4>
+      <dl>
+        <% available_filters.each do |key, description| %>
+          <dt><code><%= key %>:</code></dt>
+          <dd>Filter on values for <%= description.downcase %></dd>
+        <% end %>
+      </dl>
+    <% end %>
+  </div>
+  <% if footer? %>
+    <footer>
+      <%= footer %>
+    </footer>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Query
+      class ModalComponent < ViewComponent::Base
+        include Katalyst::HtmlAttributes
+        include Katalyst::Tables::Frontend
+
+        renders_one :footer
+
+        attr_reader :collection, :url
+
+        def initialize(collection:, **)
+          super(**)
+
+          @collection = collection
+        end
+
+        private
+
+        def default_html_attributes
+          {
+            class: "query-modal",
+            data:  {
+              tables__query_target: "modal",
+              action:               ["turbo:before-morph-attribute->tables--query#beforeMorphAttribute"],
+            },
+          }
+        end
+
+        using Collection::Type::Helpers::Extensions
+
+        def show_values?
+          current_key && attributes[current_key]
+        end
+
+        def current_key
+          unless instance_variable_defined?(:@current_key)
+            attributes.each_key do |key|
+              @current_key = key if collection.query_active?(key)
+            end
+          end
+
+          @current_key ||= nil
+        end
+
+        def attributes
+          collection.class.attribute_types
+            .select { |_, a| a.filterable? && a.type != :search }
+            .to_h
+        end
+
+        def available_filters
+          keys = attributes.keys
+
+          if current_token.present?
+            keys = keys.select { |k| k.include?(current_token) }
+          end
+
+          keys.map do |key|
+            [key, collection.model.human_attribute_name(key)]
+          end
+        end
+
+        def values_for(key)
+          collection.examples_for(key).map(&:to_s).compact_blank
+        end
+
+        def format_value(value)
+          if /\A[\w.-]*\z/.match?(value)
+            value
+          else
+            %("#{value}")
+          end
+        end
+
+        def current_token
+          return nil unless collection.position&.in?(0..collection.query.length)
+
+          prefix = collection.query[...collection.position].match(/\w*\z/)
+          suffix = collection.query[collection.position..].match(/\A\w*/)
+
+          "#{prefix}#{suffix}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+<% if content? %>
+    <%= content %>
+<% else %>
+  <%= form do |form| %>
+    <%= render query_input(form:) %>
+    <%= modal %>
+  <% end %>
+<% end %>

data/app/components/katalyst/tables/{filter_component.rb → query_component.rb}

@@ -3,7 +3,7 @@
 module Katalyst
   module Tables
     # A component for rendering a data driven filter for a collection.
-    #   <%= Katalyst::Tables::FilterComponent.new(collection: @people, url: peoples_path) %>
+    #   <%= Katalyst::Tables::QueryComponent.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.
@@ -13,30 +13,29 @@ module Katalyst
     # 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" %>
+    #   <%= Katalyst::Tables::QueryComponent.new(collection: @people, url: peoples_path) do |query| %>
+    #     <%= query.form(builder: GOVUKFormBuilder) do |form| %>
+    #       <%= form.govuk_text_field :q %>
+    #       <%= form.govuk_submit "Apply" %>
+    #       <%= modal %>
     #     <% 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 %>
+    #   <%= Katalyst::Tables::QueryComponent.new(collection: @people, url: peoples_path) do |query| %>
+    #     <% query.with_modal(collection:) do |modal| %>
+    #       <% modal.with_footer do %>
+    #         <%= link_to "Docs", docs_path %>
+    #       <% end %>
     #     <% end %>
     #   <% end %>
-    #
-    class FilterComponent < ViewComponent::Base
+    class QueryComponent < ViewComponent::Base
       include Katalyst::HtmlAttributes
       include Katalyst::Tables::Frontend
 
-      renders_one :modal, Katalyst::Tables::Filter::ModalComponent
+      renders_one :modal, Katalyst::Tables::Query::ModalComponent
 
       define_html_attribute_methods :input_attributes
 
@@ -57,32 +56,40 @@ module Katalyst
         form_with(model:  collection,
                   url:,
                   method: :get,
-                  **options) do |form|
-          concat(form.hidden_field(:sort))
+                  **options,
+                  **html_attributes) do |form|
+          concat(sort_input(form:))
 
           yield form if block_given?
         end
       end
 
-      private
+      def query_input(form:)
+        Query::InputComponent.new(form:, **input_attributes)
+      end
 
-      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
-          },
-        }
+      def sort_input(form:)
+        return if collection.default_sort?
+
+        form.hidden_field(:sort)
       end
 
-      def default_input_attributes
+      private
+
+      def default_html_attributes
         {
           data: {
-            action: "focus->tables--filter--modal#open",
+            controller:   "tables--query",
+            turbo_action: :replace,
+            action:       %w[
+              click@window->tables--query#closeModal
+              click->tables--query#openModal:stop
+              focusin@window->tables--query#closeModal
+              focusin->tables--query#openModal:stop
+              keydown.esc->tables--query#clear:stop
+              submit->tables--query#submit
+              input->tables--query#update
+            ],
           },
         }
       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_table_query_component, instance_accessor: false
         class_attribute :_default_summary_table_component, instance_accessor: false
       end
 
@@ -20,6 +21,14 @@ module Katalyst
           self._default_table_component = component
         end
 
+        # Set the table query component to be used as the default for all tables
+        # in the views rendered by this controller and its subclasses.
+        #
+        # @param component [Class] the table query component class to use
+        def default_table_query_component(component)
+          self._default_table_query_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.
@@ -35,6 +44,11 @@ module Katalyst
         self.class._default_table_component
       end
 
+      # Default table query component for this controller
+      def default_table_query_component
+        self.class._default_table_query_component
+      end
+
       # Default summary table component for this controller
       def default_summary_table_component
         self.class._default_summary_table_component

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

@@ -55,6 +55,15 @@ module Katalyst
         render(Selectable::FormComponent.new(collection:, id:, primary_key:), &)
       end
 
+      # Construct a new query interface for filtering the current page.
+      #
+      # @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 table_query_with(collection:, url: url_for(action: :index), component: nil, &)
+        component ||= default_table_query_component_class
+        render(component.new(collection:, url:), &)
+      end
+
       # Construct a new summary table component.
       #
       # @param model [ActiveRecord::Base] subject for the table
@@ -69,14 +78,6 @@ 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
@@ -84,6 +85,11 @@ module Katalyst
         component.respond_to?(:constantize) ? component.constantize : component
       end
 
+      def default_table_query_component_class
+        component = controller.try(:default_table_query_component) || QueryComponent
+        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

data/app/javascript/tables/application.js

@@ -3,7 +3,8 @@ 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";
+import QueryController from "./query_controller";
+import QueryInputController from "./query_input_controller";
 
 const Definitions = [
   {
@@ -27,8 +28,12 @@ const Definitions = [
     controllerConstructor: SelectionItemController,
   },
   {
-    identifier: "tables--filter--modal",
-    controllerConstructor: FilterModalController,
+    identifier: "tables--query",
+    controllerConstructor: QueryController,
+  },
+  {
+    identifier: "tables--query-input",
+    controllerConstructor: QueryInputController,
   },
 ];
 

data/app/javascript/tables/query_controller.js

@@ -0,0 +1,108 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class QueryController extends Controller {
+  static targets = ["modal"];
+
+  disconnect() {
+    delete this.pending;
+
+    document.removeEventListener("selectionchange", this.selection);
+  }
+
+  focus() {
+    if (document.activeElement === this.query) return;
+
+    this.query.addEventListener(
+      "focusin",
+      (e) => {
+        e.target.setSelectionRange(-1, -1);
+      },
+      { once: true },
+    );
+
+    this.query.focus();
+  }
+
+  closeModal() {
+    delete this.modalTarget.dataset.open;
+
+    if (document.activeElement === this.query) document.activeElement.blur();
+
+    document.removeEventListener("selectionchange", this.selection);
+  }
+
+  openModal() {
+    this.modalTarget.dataset.open = true;
+
+    document.addEventListener("selectionchange", this.selection);
+  }
+
+  clear() {
+    if (this.query.value === "") {
+      // if the user presses escape once, browser clears  the input
+      // if the user presses escape again, get them out of here
+      this.closeModal();
+    }
+  }
+
+  submit() {
+    const hasFocus = this.isFocused;
+    const position = hasFocus && this.query.selectionStart;
+
+    if (this.pending) {
+      clearTimeout(this.pending);
+      delete this.pending;
+    }
+
+    // prevent an unnecessary `?q=` parameter from appearing in the URL
+    if (this.query.value === "") {
+      this.query.disabled = true;
+
+      // restore input and focus after form submission
+      setTimeout(() => {
+        this.query.disabled = false;
+        if (hasFocus) this.query.focus();
+      }, 0);
+    }
+
+    // add/remove current cursor position
+    if (hasFocus && position) {
+      this.position.value = position;
+      this.position.disabled = false;
+    } else {
+      this.position.value = "";
+      this.position.disabled = true;
+    }
+  }
+
+  update = () => {
+    if (this.pending) clearTimeout(this.pending);
+    this.pending = setTimeout(() => {
+      this.element.requestSubmit();
+    }, 300);
+  };
+
+  selection = () => {
+    if (this.isFocused) this.update();
+  };
+
+  beforeMorphAttribute(e) {
+    switch (e.detail.attributeName) {
+      case "data-open":
+        e.preventDefault();
+        break;
+    }
+  }
+
+  get query() {
+    return this.element.querySelector("input[type=search]");
+  }
+
+  get position() {
+    return this.element.querySelector("input[name=p]");
+  }
+
+  get isFocused() {
+    return this.query === document.activeElement;
+  }
+}