stimulus_table_filter 0.1.0

data/lib/stimulus_table_filter/rspec/helpers.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+
+module StimulusTableFilter
+  module RSpec
+    # Provides `html` for shared examples: `response.body` in request specs, `page.html` in system specs.
+    # Override with `let(:html) { ... }` in your example group if needed.
+    module Helpers
+      def html
+        return response.body if respond_to?(:response) && response.respond_to?(:body)
+        return page.html     if respond_to?(:page) && page.respond_to?(:html)
+
+        raise StimulusTableFilter::Error, 'Define `let(:html) { ... }` or use inside a request or system spec'
+      end
+    end
+  end
+end

data/lib/stimulus_table_filter/rspec/matchers.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+RSpec::Matchers.define :have_data do |name, value|
+  chain :on, :tag
+
+  match do |html|
+    values = data_values(html, name)
+    value.nil? ? values.any? : values.include?(value.to_s)
+  end
+
+  description { value.nil? ? "have a data-#{name} attribute" : "have data-#{name}=\"#{value}\"" }
+
+  failure_message do |html|
+    found = data_values(html, name)
+    if found.empty?
+      "expected HTML to contain a data-#{name} attribute, but no element has one\n\nHTML:\n#{html}"
+    else
+      "expected HTML to contain data-#{name}=\"#{value}\", found: #{found.uniq.inspect}\n\nHTML:\n#{html}"
+    end
+  end
+
+  def data_values(html, name)
+    Nokogiri::HTML.fragment(html.to_s).css(tag || '*').filter_map { |el| el["data-#{name}"] }
+  end
+end
+
+RSpec::Matchers.define :have_data_target do |target|
+  match do |html|
+    Nokogiri::HTML.fragment(html.to_s).css('*').any? do |el|
+      el['data-table-filter-target']&.split&.include?(target.to_s)
+    end
+  end
+
+  description { "have an element with data-table-filter-target=\"#{target}\"" }
+
+  failure_message do |html|
+    present = Nokogiri::HTML.fragment(html.to_s).css('[data-table-filter-target]')
+                            .filter_map { |el| el['data-table-filter-target'] }.uniq
+    "expected HTML to contain data-table-filter-target=\"#{target}\", targets present: #{present.inspect}"
+  end
+end

data/lib/stimulus_table_filter/rspec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'rspec/helpers'
+require_relative 'rspec/matchers'
+require_relative '../spec/shared_examples/table_filter_view'
+require_relative '../spec/shared_examples/table_filter_footer'
+require_relative '../spec/shared_examples/table_filter_rows'
+
+module StimulusTableFilter
+  # Opt-in wiring for the shared examples.
+  # Call StimulusTableFilter::RSpec.install! from your spec support file.
+  module RSpec
+    def self.install!
+      ::RSpec.configure do |config|
+        config.include Helpers
+      end
+    end
+  end
+end

data/lib/stimulus_table_filter/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StimulusTableFilter
+  VERSION = '0.1.0'
+end

data/lib/stimulus_table_filter/view_helper/container.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module StimulusTableFilter
+  module ViewHelper
+    def table_filter_container_tag(sort: 'name', dir: 'asc', page: nil, page_size: nil, url_key: nil,
+                                   debounce_ms: nil, tag: :div, **opts, &)
+      data = container_data(sort:, dir:, page:, page_size:, url_key:,
+                            debounce_ms:).merge(opts.delete(:data) || {})
+      content_tag(tag, data: data, **opts, &)
+    end
+
+    private
+
+    def base_container_data(sort:, dir:, page: nil)
+      base = { controller: 'table-filter', table_filter_sort_value: sort, table_filter_dir_value: dir }
+      base[:table_filter_page_value] = page.to_s if page
+      base
+    end
+
+    def container_data(sort:, dir:, page: nil, page_size: nil, url_key: nil, debounce_ms: nil)
+      base = base_container_data(sort:, dir:, page:)
+      base = base.merge(table_filter_page_size_value: page_size.to_s)     if page_size
+      base = base.merge(table_filter_url_key_value: url_key.to_s)         if url_key
+      base = base.merge(table_filter_debounce_ms_value: debounce_ms.to_s) if debounce_ms
+      base
+    end
+  end
+end

data/lib/stimulus_table_filter/view_helper/controls.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module StimulusTableFilter
+  module ViewHelper
+    def table_filter_search_tag(**opts) = tag.input(type: 'search', data: target_data('search', opts), **opts)
+
+    def table_filter_filter_btn_tag(value, label, dimension: nil, **opts)
+      data = with_data({ filter_btn: value }, opts)
+      data[:filter_dimension] = dimension if dimension
+      content_tag(:button, label, data: data, **opts)
+    end
+
+    def table_filter_empty_row_tag(**opts, &)
+      data  = target_data('emptyRow', opts)
+      klass = ['hidden', *Array(opts.delete(:class))].join(' ')
+      content_tag(:tr, data: data, class: klass, **opts, &)
+    end
+
+    def table_filter_active_filter_tag(dimension: nil, **opts, &)
+      data = target_data('filterDisplay', opts)
+      data[:filter_dimension] = dimension if dimension
+      content_tag(:span, data: data, hidden: true, **opts, &)
+    end
+
+    def table_filter_select_tag(options, dimension: nil, **opts)
+      data = with_data({ table_filter_target: 'filterSelect' }, opts)
+      data[:filter_dimension] = dimension if dimension
+      pairs = normalize_options(options)
+      content_tag(:select, data: data, **opts) { render_options(pairs) }
+    end
+
+    private
+
+    def option_tag(pair) = content_tag(:option, pair.first, value: pair.last)
+    def render_options(pairs) = safe_join(pairs.map(&method(:option_tag)))
+
+    def normalize_options(options)
+      pairs = options.is_a?(Hash) ? options.to_a : options
+      pairs.map { |pair| pair.is_a?(Array) ? pair : [pair, pair] }
+    end
+  end
+end

data/lib/stimulus_table_filter/view_helper/rows.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module StimulusTableFilter
+  module ViewHelper
+    def table_filter_row_attrs(name:, filters: {}, sort: {}, searchable: nil, group: nil)
+      data = { table_filter_target: 'row', name: name.to_s.downcase, **filter_data(filters), **sort_data(sort) }
+      extras = { searchable: searchable&.to_s&.downcase, group: group&.to_s }.compact
+      { data: data.merge(extras) }
+    end
+
+    def table_filter_row_tag(name:, filters: {}, sort: {}, searchable: nil, group: nil,
+                             tag: :tr, **html_options, &)
+      data = with_data(
+        table_filter_row_attrs(name: name, filters: filters, sort: sort,
+                               searchable: searchable, group: group)[:data], html_options
+      )
+      content_tag(tag, data: data, **html_options, &)
+    end
+
+    def table_filter_group_header_tag(group, tag: :tr, **opts, &)
+      data = with_data({ table_filter_target: 'groupHeader', group: group.to_s }, opts)
+      content_tag(tag, data: data, **opts, &)
+    end
+
+    private
+
+    def filter_key(key) = :"filter_#{key}"
+    def filter_data(filters) = filters.transform_keys(&method(:filter_key)).transform_values(&:to_s)
+    def sort_key(key) = :"sort_#{key}"
+    def sort_data(sort) = sort.transform_keys(&method(:sort_key)).transform_values(&:to_s)
+  end
+end

data/lib/stimulus_table_filter/view_helper/sort.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module StimulusTableFilter
+  module ViewHelper
+    def table_filter_sort_btn_tag(col, label, type: nil, **)
+      table_filter_build_sort_trigger(:button, col, label, type: type, **)
+    end
+
+    def table_filter_sort_th_tag(col, label, type: nil, **)
+      table_filter_build_sort_trigger(:th, col, label, type: type, **)
+    end
+
+    def table_filter_column_tag(col:, label:, type: nil, sortable: true, **)
+      return content_tag(:th, label, scope: 'col', **) unless sortable
+
+      table_filter_sort_th_tag(col, label, type: type, **)
+    end
+
+    private
+
+    def sort_trigger_icon = content_tag(:span, '', data: { sort_icon: '' })
+    def sort_btn_base(col, type) = type ? { sort_btn: col, sort_type: type } : { sort_btn: col }
+    def sort_trigger_data(col, type, opts) = sort_btn_base(col, type).merge(opts.delete(:data) || {})
+
+    def table_filter_build_sort_trigger(tag, col, label, type: nil, **opts)
+      data = sort_trigger_data(col, type, opts)
+      opts = { scope: 'col' }.merge(opts) if tag == :th
+      content_tag(tag, ERB::Util.html_escape(label) + sort_trigger_icon, data: data, **opts)
+    end
+  end
+end

data/lib/stimulus_table_filter/view_helper/stats.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module StimulusTableFilter
+  module ViewHelper
+    def table_filter_prev_btn_tag(label = '←', **opts)
+      content_tag(:button, label, data: with_data({ prev_page: '', table_filter_target: 'prevPage' }, opts), **opts)
+    end
+
+    def table_filter_next_btn_tag(label = '→', **opts)
+      content_tag(:button, label, data: with_data({ next_page: '', table_filter_target: 'nextPage' }, opts), **opts)
+    end
+
+    def table_filter_page_info_tag(**opts) = content_tag(:span, '', data: target_data('pageInfo', opts), **opts)
+
+    def table_filter_match_count_tag(**)  = table_filter_stat_span('matchCount', **)
+    def table_filter_total_count_tag(**)  = table_filter_stat_span('totalCount', **)
+    def table_filter_match_pct_tag(**)    = table_filter_stat_span('matchPct', **)
+
+    def table_filter_count_tag(dimension:, value:, **opts)
+      data = with_data({ count_dimension: dimension, count_value: value }, opts)
+      content_tag(:span, '', data: data, **opts)
+    end
+
+    def table_filter_footer_tag(colspan: nil, tag: :tfoot, **opts, &)
+      content_tag(tag) do
+        content_tag(:tr) do
+          td_opts = colspan ? { colspan: colspan } : {}
+          content_tag(:td, **td_opts, **opts) { footer_content(&) }
+        end
+      end
+    end
+
+    private
+
+    def footer_content(&)
+      return default_footer_content unless block_given?
+
+      capture(table_filter_match_count_tag, table_filter_total_count_tag, &)
+    end
+
+    def table_filter_stat_span(target, **opts) = content_tag(:span, '', data: target_data(target, opts), **opts)
+
+    def default_footer_content
+      safe_join([table_filter_match_count_tag, ' of ', table_filter_total_count_tag])
+    end
+  end
+end

data/lib/stimulus_table_filter/view_helper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module StimulusTableFilter
+  module ViewHelper
+    private
+
+    def with_data(base, opts) = base.merge(opts.delete(:data) || {})
+    def target_data(target, opts) = with_data({ table_filter_target: target }, opts)
+  end
+end
+
+require_relative 'view_helper/container'
+require_relative 'view_helper/rows'
+require_relative 'view_helper/controls'
+require_relative 'view_helper/sort'
+require_relative 'view_helper/stats'

data/lib/stimulus_table_filter.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'stimulus_table_filter/version'
+require 'stimulus_table_filter/error'
+require 'stimulus_table_filter/view_helper'
+require 'stimulus_table_filter/engine' if defined?(Rails)