stimulus_table_filter 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd1d293fa4373f23cb2eb542feb797e20b73b994564af5422e1bb69cfb370af4
-  data.tar.gz: 80a795894d382356b03d83ab003727c4dd5e786f81ca140106b33417ecabeab6
+  metadata.gz: 495418a93784ca089dccd7fca9636a3bcc89a7e2f42599fc0cb9c6676be34ef7
+  data.tar.gz: c7486ef81d34dc5cd0d09ff3f2bd5047105f2810c25a296b960f1cdcaacddba1
 SHA512:
-  metadata.gz: d27af095bbddab3441ed10e65215c2e92c2bdbb2d10111ac4ffee02adc7fc9ee0898087019329b43e2b649d8f5119be42639ab2ba150a427ab5be5e9ce0b17f6
-  data.tar.gz: 8d52a264133b2aed8e2737392b6ba0a86443f35b95be1a0942204e04297cb86b05e5e6100ffcac25a42e81c5a7f122c0632b5cbe8bd8bbdfb7f7d85ad2c577f6
+  metadata.gz: f9f256274e5dc8b69d2db008c7547781987d20dd67a0825f0c9e89af99c6b4b715bf6519ba80017073fe35cd6662e8776177ea9f0abd7ff78b8550ffc7e103f4
+  data.tar.gz: b61979d520487ce847e45c00d7d66c66c91adb8eaebb54a9a5742947825e666fda4c947fede3bada960eaf1546f4e584d65cae21f07b75c867cfb41310bf4f4b

data/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.2.0] - 2026-10-15
+
+- Add `table_filter_bar_tag`: a search input and optional filter buttons in one toolbar. It
+  raises `StimulusTableFilter::Error` when `filters:` is given without `dimension:`
+
+## [0.1.1] - 2026-08-31
+
+- `table_filter_container_tag` accepts a `search:` option and emits
+  `data-table-filter-search-value`, matching the documented data-attribute contract
+- README: document that `table_filter_footer_tag` wraps its content in a footer element, a
+  `<tr>` and a `<td>`; correct the URL-state and programmatic-API behavior notes
+
 ## [0.1.0] - 2026-08-25
 
 Initial release.
@@ -13,4 +25,5 @@ Initial release.
 - RSpec support: shared examples plus `have_data` / `have_data_target` matchers
 - CI: RuboCop, RSpec and JavaScript tests across Ruby 3.2–3.4 and Rails 7.0–8.1
 
+[0.1.1]: https://github.com/icoluccio/stimulus-table-filter/releases/tag/v0.1.1
 [0.1.0]: https://github.com/icoluccio/stimulus-table-filter/releases/tag/v0.1.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stimulus_table_filter (0.1.0)
+    stimulus_table_filter (0.2.0)
       railties (>= 7.0, < 9)
 
 GEM
@@ -285,7 +285,7 @@ CHECKSUMS
   securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
   sexp_processor (4.17.5) sha256=ae2b48ba98353d5d465ce8759836b7a05f2e12c5879fcd14d7815b026de32f0e
   simplecov (1.1.1) sha256=25825ef13f0b2e74694d769817dad6ab8e90131dabdaa666e522fea105521e78
-  stimulus_table_filter (0.1.0)
+  stimulus_table_filter (0.2.0)
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
   tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b

data/README.md

@@ -110,13 +110,8 @@ A complete filterable table in one view partial:
 
 ```erb
 <%= table_filter_container_tag do %>
-  <%# Search + filter bar %>
-  <div>
-    <%= table_filter_search_tag(placeholder: "Search users…") %>
-    <%= table_filter_filter_btn_tag("all",      "All",      dimension: "status") %>
-    <%= table_filter_filter_btn_tag("active",   "Active",   dimension: "status") %>
-    <%= table_filter_filter_btn_tag("archived", "Archived", dimension: "status") %>
-  </div>
+  <%= table_filter_bar_tag(placeholder: "Search users…", dimension: "status",
+        filters: { "all" => "All", "active" => "Active", "archived" => "Archived" }) %>
 
   <table>
     <thead>
@@ -176,6 +171,7 @@ the controller reads on connect.
 | `page_size:` | `nil` | Rows per page (omit or `0` to disable pagination) |
 | `url_key:` | `nil` | URL param prefix (default `tf`); set per table to namespace multiple tables |
 | `debounce_ms:` | `nil` | Search debounce in ms (default `0` = immediate) |
+| `search:` | `nil` | Initial search text (emits `data-table-filter-search-value`) |
 | `tag:` | `:div` | Wrapping HTML element |
 
 Every helper accepts `**opts` and passes them through to the underlying tag.
@@ -224,6 +220,28 @@ filters. Omit `filters:` and the filter helpers entirely for a search-and-sort-o
 Filters rows by matching `data-name`, or `data-searchable` when present. Case-insensitive
 substring match.
 
+### Toolbar
+
+`table_filter_bar_tag` renders the search input and, when `filters:` is given, a group of filter
+buttons inside one `<div>`:
+
+```erb
+<%= table_filter_bar_tag(placeholder: "Search users…", dimension: "status",
+      filters: { "all" => "All", "active" => "Active" },
+      class: "flex gap-2", search: { class: "input" }, group: { class: "join" }, button: { class: "btn" }) %>
+```
+
+| Option | Applies to |
+| --- | --- |
+| `placeholder:` | The search input |
+| `filters:` | `{ value => label }`; one button per entry. Omit it for a search-only bar. No group renders |
+| `dimension:` | The dimension every button acts on. **Required** with `filters:`. Without it the helper raises `StimulusTableFilter::Error` |
+| `search:`, `group:`, `button:` | Extra attributes (`class:`, `data:`, ...) for the input, the button group `<div>` and each button |
+| any other option | The outer `<div>` |
+
+It wraps `table_filter_search_tag` and `table_filter_filter_btn_tag`. Call those directly when
+you need a different layout.
+
 ### Filter buttons
 
 ```erb
@@ -315,6 +333,9 @@ The default footer shows how many rows match the current filter and search, out
 <!-- renders: <span>12</span> of <span>87</span> -->
 ```
 
+The helper wraps the content in the footer element (a `<tfoot>` by default), a `<tr>`, and a
+`<td>`; `colspan:` applies to that cell and `tag:` replaces only the outer element.
+
 Or build your own footer. The block receives the match-count and total-count spans:
 
 ```erb
@@ -399,11 +420,14 @@ Behavior notes:
 - **Footer stats**: the match count covers every row that passes the active filters and search,
   across all pages. Count tags populate with the number of matching rows whose dimension value
   equals the tag's value.
-- **URL state**: every filter dimension, sort, direction, page and search sync to
-  `URLSearchParams` on every change (dimensions as `tf_filter_{dimension}` params) and the
-  controller restores them on connect. Namespace multiple tables with `data-table-filter-url-key-value`.
+- **URL state**: the controller syncs filter dimensions, sort, direction, page and search to
+  `URLSearchParams` when the user changes them (dimensions as `tf_filter_{dimension}` params)
+  and restores them on connect without rewriting the URL. Namespace multiple tables with
+  `data-table-filter-url-key-value`.
 - **Event handling**: the controller delegates all events itself; individual elements
-  need no `data-action`. `setFilter`, `sortBy` and `search` are also callable programmatically.
+  need no `data-action`. Call `search()` programmatically. For filters and sort, set the
+  Stimulus values and refresh, e.g.
+  `controller.filterDimensionsValue = { status: 'active' }; controller.refresh()`.
 
 ### RSpec shared examples
 

data/app/assets/javascripts/stimulus_table_filter/table_filter_controller.js

@@ -38,6 +38,7 @@ export default class extends Controller {
 
   connect() {
     this.#readUrlState()
+    if (this.hasSearchTarget && this.searchValue) this.searchTarget.value = this.searchValue
     this.element.addEventListener("click",  this.#onClick)
     this.element.addEventListener("input",  this.#onInput)
     this.element.addEventListener("change", this.#onChange)

data/lib/stimulus_table_filter/version.rb

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

data/lib/stimulus_table_filter/view_helper/container.rb

@@ -3,9 +3,9 @@
 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, &)
+                                   debounce_ms: nil, search: nil, tag: :div, **opts, &)
       data = container_data(sort:, dir:, page:, page_size:, url_key:,
-                            debounce_ms:).merge(opts.delete(:data) || {})
+                            debounce_ms:, search:).merge(opts.delete(:data) || {})
       content_tag(tag, data: data, **opts, &)
     end
 
@@ -17,11 +17,12 @@ module StimulusTableFilter
       base
     end
 
-    def container_data(sort:, dir:, page: nil, page_size: nil, url_key: nil, debounce_ms: nil)
+    def container_data(sort:, dir:, page: nil, page_size: nil, url_key: nil, debounce_ms: nil, search: 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 = base.merge(table_filter_search_value: search.to_s)           if search
       base
     end
   end

data/lib/stimulus_table_filter/view_helper/controls.rb

@@ -4,6 +4,14 @@ module StimulusTableFilter
   module ViewHelper
     def table_filter_search_tag(**opts) = tag.input(type: 'search', data: target_data('search', opts), **opts)
 
+    # Raises StimulusTableFilter::Error if +filters+ is given without +dimension+.
+    def table_filter_bar_tag(placeholder: nil, filters: {}, dimension: nil, search: {}, group: {}, button: {}, **opts)
+      content_tag(:div, **opts) do
+        safe_join([table_filter_search_tag(placeholder: placeholder, **search),
+                   table_filter_button_group(filters, dimension, group, button)])
+      end
+    end
+
     def table_filter_filter_btn_tag(value, label, dimension: nil, **opts)
       data = with_data({ filter_btn: value }, opts)
       data[:filter_dimension] = dimension if dimension
@@ -31,6 +39,18 @@ module StimulusTableFilter
 
     private
 
+    def table_filter_button_group(filters, dimension, group, button)
+      return if filters.empty?
+
+      content_tag(:div, table_filter_buttons(filters, dimension, button), **group)
+    end
+
+    def table_filter_buttons(filters, dimension, button)
+      raise Error, 'table_filter_bar_tag requires dimension: when filters are given' unless dimension
+
+      safe_join(filters.map { |value, label| table_filter_filter_btn_tag(value, label, dimension:, **button) })
+    end
+
     def option_tag(pair) = content_tag(:option, pair.first, value: pair.last)
     def render_options(pairs) = safe_join(pairs.map(&method(:option_tag)))
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_table_filter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - icoluccio
@@ -101,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Client-side table filtering, sorting and search for Rails
 test_files: []