stimulus_table_filter 0.1.0

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

@@ -0,0 +1,75 @@
+// Full data-attribute contract: README.md, "Data-attribute contract".
+
+export const ALL_FILTER = "all"
+export const HIDDEN_CLASS = "hidden"
+export const HIDDEN_STYLE = "none"
+export const ACTIVE_BUTTON_CLASS = "btn-active"
+export const ARIA_SORT_NONE = "none"
+export const NEUTRAL_ICON = " ↕"
+
+export const SELECTORS = {
+  filterButton: "[data-filter-btn]",
+  sortButton: "[data-sort-btn]",
+  sortIcon: "[data-sort-icon]",
+  prevPageButton: "[data-prev-page]",
+  nextPageButton: "[data-next-page]",
+  count: "[data-count-dimension]"
+}
+
+export const PAGE_STEPS = [[SELECTORS.prevPageButton, -1], [SELECTORS.nextPageButton, 1]]
+
+export const TARGETS = {
+  search: "search",
+  row: "row",
+  matchCount: "matchCount",
+  totalCount: "totalCount",
+  matchPct: "matchPct",
+  emptyRow: "emptyRow",
+  prevPage: "prevPage",
+  nextPage: "nextPage",
+  pageInfo: "pageInfo",
+  groupHeader: "groupHeader",
+  filterDisplay: "filterDisplay",
+  filterSelect: "filterSelect"
+}
+
+export const DIRECTIONS = {
+  asc:  { opposite: "desc", multiplier: 1,  aria: "ascending",  icon: " ↑" },
+  desc: { opposite: "asc",  multiplier: -1, aria: "descending", icon: " ↓" }
+}
+
+export const pascalCase = (value) => value
+  .split("-")
+  .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+  .join("")
+
+// Dataset key carrying a row's value for a filter dimension:
+// data-filter-payment-status → dataset.filterPaymentStatus
+export const dimensionDatasetKey = (dimension) => `filter${pascalCase(dimension)}`
+
+export const dimensionValue = (row, dimension) => row.dataset[dimensionDatasetKey(dimension)]
+
+const parseSlashDate = (value, dayFirst) => {
+  const [first, second, year] = value.split("/")
+  const day = dayFirst ? first : second
+  const month = dayFirst ? second : first
+  return new Date(+year, month - 1, +day).getTime()
+}
+
+// data-sort-type → parser: turns a cell string into a comparable number; strings stay locale-aware.
+export const SORT_TYPES = {
+  string:      { locale: true },
+  numeric:     { parse: value => (value === "" ? null : parseFloat(value)) },
+  date:        { parse: value => new Date(value).getTime() },
+  "date-dmy":  { parse: value => parseSlashDate(value, true) },
+  "date-mdy":  { parse: value => parseSlashDate(value, false) }
+}
+
+// Defaults are dropped from the URL when equal; parse normalizes values read back.
+// Filter dimensions serialize separately as tf_filter_{dimension} params.
+export const URL_FIELDS = [
+  { key: "sort",   default: "name" },
+  { key: "dir",    default: "asc", parse: value => (DIRECTIONS[value] ? value : undefined) },
+  { key: "page",   default: 1,     parse: value => parseInt(value) || 1 },
+  { key: "search", default: "" }
+]

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

@@ -0,0 +1,234 @@
+import { Controller } from "@hotwired/stimulus"
+import {
+  ALL_FILTER,
+  DIRECTIONS,
+  HIDDEN_CLASS,
+  PAGE_STEPS,
+  SELECTORS,
+  TARGETS
+} from "stimulus_table_filter/table_filter"
+import { PageNavigator } from "stimulus_table_filter/page_navigator"
+import { RowMatcher } from "stimulus_table_filter/row_matcher"
+import { RowSorter } from "stimulus_table_filter/row_sorter"
+import { RowStats } from "stimulus_table_filter/row_stats"
+import { TableView } from "stimulus_table_filter/table_filter_view"
+import { UrlState } from "stimulus_table_filter/url_state"
+
+export default class extends Controller {
+  static targets = Object.values(TARGETS)
+  static values  = {
+    filterDimensions: { type: Object, default: {} },
+    sort:             { type: String, default: "name" },
+    dir:              { type: String, default: "asc" },
+    page:             { type: Number, default: 1 },
+    search:           { type: String, default: "" },
+    pageSize:         { type: Number, default: 0 },
+    urlKey:           { type: String, default: "tf" },
+    debounceMs:       { type: Number, default: 0 }
+  }
+
+  #debounceTimer = null
+  #interacted    = false   // URL state is only written after the first user interaction
+  #view          = new TableView(this)
+
+  // Bound handlers stored so disconnect() can remove the same references
+  #onClick  = (e) => this.#handleClick(e)
+  #onInput  = (e) => this.#handleInput(e)
+  #onChange = (e) => this.#handleChange(e)
+
+  connect() {
+    this.#readUrlState()
+    this.element.addEventListener("click",  this.#onClick)
+    this.element.addEventListener("input",  this.#onInput)
+    this.element.addEventListener("change", this.#onChange)
+    this.refresh()
+  }
+
+  disconnect() {
+    this.element.removeEventListener("click",  this.#onClick)
+    this.element.removeEventListener("input",  this.#onInput)
+    this.element.removeEventListener("change", this.#onChange)
+    clearTimeout(this.#debounceTimer)
+  }
+
+  // ── Public API (also callable from external elements as data-action handlers) ────
+
+  setFilter(event) { this.#applyFilter(event.currentTarget.dataset.filterBtn, event.currentTarget.dataset.filterDimension) }
+  sortBy(event)    { this.#applySort(event.currentTarget.dataset.sortBtn) }
+  search()         { this.pageValue = 1; this.refresh() }
+
+  refresh() {
+    this.#filterRows()
+    this.#reorder()
+    this.#renderStats()   // counts the full filtered set; must run before #applyPage
+    this.#applyPage()
+    this.#view.renderGroupHeaders(this.rowTargets)   // only header groups with rows on this page stay visible
+    this.#view.renderFilterButtons(this.filterDimensionsValue)
+    this.#view.renderSortTriggers(this.sortValue, this.dirValue)
+    this.#view.renderFilterDisplay(this.filterDimensionsValue)
+    this.#view.renderFilterSelect(this.filterDimensionsValue)
+    this.#view.renderCounts(this.#matchedRows())
+    this.#view.renderPagination(this.pageValue, this.#matchedRows().length, this.#navigator())
+    if (this.#interacted) this.#writeUrlState()
+  }
+
+  #handleClick(event) {
+    if (this.#clickFilter(event)) return
+    if (this.#clickSort(event)) return
+    this.#clickPage(event)
+  }
+
+  #clickFilter(event) {
+    const btn = event.target.closest(SELECTORS.filterButton)
+    if (!btn) return false
+    this.#applyFilter(btn.dataset.filterBtn, btn.dataset.filterDimension)
+    return true
+  }
+
+  #clickSort(event) {
+    const btn = event.target.closest(SELECTORS.sortButton)
+    if (!btn) return false
+    this.#applySort(btn.dataset.sortBtn)
+    return true
+  }
+
+  #clickPage(event) {
+    for (const [selector, step] of PAGE_STEPS) {
+      if (!event.target.closest(selector)) continue
+      this.#goToPage(step)
+      return true
+    }
+    return false
+  }
+
+  // Every user-driven change resets pagination, marks the session as
+  // interactive and re-renders the table.
+  #rerun(update) {
+    update()
+    this.pageValue = 1
+    this.#interacted = true
+    this.refresh()
+  }
+
+  #applyFilter(value, dimension) {
+    if (!dimension) return
+    this.#rerun(() => this.#toggleDimensionFilter(dimension, value))
+  }
+
+  #applySort(col) {
+    this.#rerun(() => {
+      this.dirValue = this.sortValue === col ? DIRECTIONS[this.dirValue].opposite : "asc"
+      this.sortValue = col
+    })
+  }
+
+  #handleInput(event) {
+    if (!this.#hasTargetToken(event.target, "search")) return
+    this.searchValue = event.target.value
+    this.#interacted = true
+    this.pageValue = 1
+    this.debounceMsValue ? this.#deferRefresh() : this.refresh()
+  }
+
+  #deferRefresh() {
+    clearTimeout(this.#debounceTimer)
+    this.#debounceTimer = setTimeout(() => this.refresh(), this.debounceMsValue)
+  }
+
+  // Select always replaces (single-choice); it cannot represent multi-value state.
+  #handleChange(event) {
+    const select = event.target
+    if (!this.#hasTargetToken(select, "filterSelect")) return
+    this.#rerun(() => this.#setDimensionFilter(select.dataset.filterDimension, select.value))
+  }
+
+  // An element may carry several space-separated target names; match tokens, not the whole string.
+  #hasTargetToken(el, token) {
+    return (el.dataset?.tableFilterTarget || "").split(" ").includes(token)
+  }
+
+  // Toggles a value within a dimension's list; "all" resets, and an emptied
+  // list removes the dimension.
+  #toggleDimensionFilter(dimension, value) {
+    const current = this.filterDimensionsValue[dimension] ?? ALL_FILTER
+    this.#setDimensionFilter(dimension, RowMatcher.toggledFilter(current, value))
+  }
+
+  // A missing/empty value removes the dimension from the filter state.
+  #setDimensionFilter(dimension, value) {
+    if (!dimension) return
+    const { [dimension]: _omitted, ...rest } = this.filterDimensionsValue
+    const inactive = value === undefined || value === ALL_FILTER
+    this.filterDimensionsValue = inactive ? rest : { ...rest, [dimension]: value }
+  }
+
+  #navigator() {
+    return new PageNavigator(this.pageSizeValue)
+  }
+
+  #matchedRows() {
+    return this.rowTargets.filter(r => !r.classList.contains(HIDDEN_CLASS))
+  }
+
+  #filterRows() {
+    const matcher = new RowMatcher(this.searchValue, this.filterDimensionsValue)
+    this.#view.renderRowVisibility(this.rowTargets, matcher)
+  }
+
+  #renderStats() {
+    const stats = RowStats.compute(this.rowTargets, this.#matchedRows())
+    this.#view.renderStats(stats)
+    this.#view.renderEmptyRow(stats.matched)
+  }
+
+  #applyPage() {
+    const navigator = this.#navigator()
+    this.#view.clearPageWindow(this.rowTargets)
+    if (!navigator.enabled) return
+
+    const matched = this.#matchedRows()
+    this.pageValue = navigator.clamp(this.pageValue, matched.length)   // stale ?tf_page= from the URL
+    this.#view.showPageWindow(matched, navigator.window(this.pageValue))
+  }
+
+  #goToPage(step) {
+    const navigator = this.#navigator()
+    const target = navigator.step(this.pageValue, step, this.#matchedRows().length)
+    if (target === this.pageValue) return
+    this.pageValue = target
+    this.#interacted = true
+    this.#applyPage()
+    this.#view.renderPagination(this.pageValue, this.#matchedRows().length, navigator)
+  }
+
+  #reorder() {
+    this.#view.reorderRows(this.#sorter().sort(this.rowTargets))
+  }
+
+  #sorter() {
+    // Match by value instead of an interpolated attribute selector, since the sort
+    // column can come from the URL and selector injection must stay impossible.
+    const trigger = [...this.element.querySelectorAll(SELECTORS.sortButton)]
+      .find(btn => btn.dataset.sortBtn === this.sortValue)
+    return new RowSorter(this.sortValue, trigger?.dataset.sortType, this.dirValue)
+  }
+
+  #readUrlState() {
+    this.#applyUrlState(UrlState.read(this.urlKeyValue))
+  }
+
+  // URL_FIELDS keys are Stimulus values, so state applies by name.
+  #applyUrlState(state) {
+    for (const [key, value] of Object.entries(state)) this[`${key}Value`] = value
+  }
+
+  #writeUrlState() {
+    UrlState.write(this.urlKeyValue, {
+      filterDimensions: this.filterDimensionsValue,
+      sort:             this.sortValue,
+      dir:              this.dirValue,
+      search:           this.searchValue.trim(),
+      page:             this.pageValue
+    })
+  }
+}

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

@@ -0,0 +1,149 @@
+import {
+  ACTIVE_BUTTON_CLASS,
+  ALL_FILTER,
+  ARIA_SORT_NONE,
+  DIRECTIONS,
+  HIDDEN_CLASS,
+  HIDDEN_STYLE,
+  NEUTRAL_ICON,
+  SELECTORS,
+  TARGETS,
+  dimensionValue,
+  pascalCase
+} from "stimulus_table_filter/table_filter"
+import { FilterList } from "stimulus_table_filter/filter_list"
+import { RowStats } from "stimulus_table_filter/row_stats"
+
+export class TableView {
+  constructor(controller) {
+    this.controller = controller
+  }
+
+  renderRowVisibility(rows, matcher) {
+    rows.forEach(row => row.classList.toggle(HIDDEN_CLASS, !matcher.matches(row)))
+  }
+
+  reorderRows(rows) {
+    Map.groupBy(rows, row => row.parentElement)
+       .forEach((groupRows, parent) => parent.append(...groupRows))
+  }
+
+  renderGroupHeaders(rows) {
+    this.controller.groupHeaderTargets.forEach(header => {
+      const hasVisibleRows = rows.some(r => r.dataset.group === header.dataset.group && this.isVisible(r))
+      header.classList.toggle(HIDDEN_CLASS, !hasVisibleRows)
+    })
+  }
+
+  clearPageWindow(rows) {
+    rows.forEach(row => row.style.removeProperty("display"))
+  }
+
+  showPageWindow(rows, { start, end }) {
+    rows.forEach((row, index) => {
+      if (index < start || index >= end) row.style.display = HIDDEN_STYLE
+    })
+  }
+
+  renderStats({ matched, total }) {
+    const c = this.controller
+    window.__targetDebug = Object.fromEntries(
+      ['matchCount', 'totalCount', 'matchPct'].map((name) => {
+        const key = pascalCase(name)
+        const dom = c.element.querySelector(`[data-table-filter-target~="${name}"]`)
+        return [name, {
+          has: c[`has${key}Target`],
+          get: c[`${key}Target`] ? 'el' : String(c[`${key}Target`]),
+          dom: dom ? 'el' : 'missing'
+        }]
+      })
+    )
+    this.#target(TARGETS.matchCount).textContent = matched
+    this.#target(TARGETS.totalCount).textContent = total
+    this.#target(TARGETS.matchPct).textContent = `${RowStats.percentage(matched, total)}%`
+  }
+
+  renderCounts(matchedRows) {
+    this.controller.element.querySelectorAll(SELECTORS.count).forEach(el => {
+      el.textContent = matchedRows
+        .filter(row => dimensionValue(row, el.dataset.countDimension) === el.dataset.countValue).length
+    })
+  }
+
+  renderEmptyRow(matched) {
+    this.#target(TARGETS.emptyRow).classList.toggle(HIDDEN_CLASS, matched > 0)
+  }
+
+  renderFilterButtons(dimensions) {
+    this.controller.element.querySelectorAll(SELECTORS.filterButton).forEach(btn => {
+      const list = this.listFor(dimensions, this.dimensionOf(btn))
+      const isActive = btn.dataset.filterBtn === ALL_FILTER ? list.isEmpty : list.has(btn.dataset.filterBtn)
+      this.setActiveState(btn, isActive)
+    })
+  }
+
+  renderSortTriggers(sortValue, dirValue) {
+    const direction = DIRECTIONS[dirValue]
+    this.controller.element.querySelectorAll(SELECTORS.sortButton).forEach(btn => {
+      const active = btn.dataset.sortBtn === sortValue
+      this.renderSortTriggerState(btn, active, direction)
+      this.#sortIcon(btn).textContent = active ? direction.icon : NEUTRAL_ICON
+    })
+  }
+
+  renderSortTriggerState(btn, active, direction) {
+    if (btn.tagName === "TH") {
+      btn.setAttribute("aria-sort", active ? direction.aria : ARIA_SORT_NONE)
+      return
+    }
+    this.setActiveState(btn, active)
+  }
+
+  renderFilterDisplay(dimensions) {
+    const display = this.#target(TARGETS.filterDisplay)
+    const list = this.listFor(dimensions, this.dimensionOf(display))
+    display.hidden = list.isEmpty
+    display.textContent = list.toString().replace(/,/g, ", ")
+  }
+
+  renderFilterSelect(dimensions) {
+    const select = this.#target(TARGETS.filterSelect)
+    select.value = this.listFor(dimensions, this.dimensionOf(select)).toString()
+  }
+
+  renderPagination(page, matchedTotal, navigator) {
+    if (!navigator.enabled) return
+    this.#target(TARGETS.prevPage).disabled = page <= 1
+    this.#target(TARGETS.nextPage).disabled = page >= navigator.pageCount(matchedTotal)
+    this.#target(TARGETS.pageInfo).textContent = navigator.info(page, matchedTotal)
+  }
+
+  isVisible(row) {
+    return !row.classList.contains(HIDDEN_CLASS) && row.style.display !== HIDDEN_STYLE
+  }
+
+  setActiveState(btn, isActive) {
+    btn.classList.toggle(ACTIVE_BUTTON_CLASS, isActive)
+    btn.setAttribute("aria-pressed", isActive ? "true" : "false")
+  }
+
+  // A trigger's data-filter-dimension names the dimension it acts on.
+  dimensionOf(el) {
+    return el.dataset.filterDimension
+  }
+
+  listFor(dimensions, dimension) {
+    return new FilterList(dimensions[dimension] ?? ALL_FILTER)
+  }
+
+  // Writes to a missing target land on a detached sink element and are discarded.
+  // has is PascalCase (hasMatchCountTarget); the value getter is camelCase (matchCountTarget).
+  #target(name) {
+    const controller = this.controller
+    return controller[`has${pascalCase(name)}Target`] ? controller[`${name}Target`] : document.createElement("template")
+  }
+
+  #sortIcon(btn) {
+    return btn.querySelector(SELECTORS.sortIcon) ?? document.createElement("template")
+  }
+}

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

@@ -0,0 +1,51 @@
+import { URL_FIELDS } from "stimulus_table_filter/table_filter"
+
+export class UrlState {
+  static read(prefix) {
+    const state = {}
+    const params = this.withParams(prefix, (params, field, param) => {
+      if (!params.has(param)) return
+      const value = field.parse ? field.parse(params.get(param)) : params.get(param)
+      if (value !== undefined) state[field.key] = value
+    })
+    const dimensions = this.readDimensions(params, prefix)
+    if (dimensions.size) state.filterDimensions = Object.fromEntries(dimensions)
+    return state
+  }
+
+  static write(prefix, state) {
+    const params = this.withParams(prefix, (params, field, param) => {
+      const value = state[field.key]
+      if (value === undefined || value === field.default) params.delete(param)
+      else params.set(param, String(value))
+    })
+    const dimensions = state.filterDimensions ?? {}
+    const marker = `${prefix}_filter_`
+    for (const key of [...params.keys()]) {
+      if (key.startsWith(marker) && !Object.hasOwn(dimensions, key.slice(marker.length))) params.delete(key)
+    }
+    for (const [dimension, value] of Object.entries(dimensions)) {
+      const param = `${prefix}_filter_${dimension}`
+      if (!value || value === "all") params.delete(param)
+      else params.set(param, value)
+    }
+    history.replaceState(null, "", `${location.pathname}?${params}`)
+  }
+
+  static withParams(prefix, apply) {
+    const params = new URLSearchParams(location.search)
+    for (const field of URL_FIELDS) apply(params, field, `${prefix}_${field.key}`)
+    return params
+  }
+
+  static readDimensions(params, prefix) {
+    const dimensions = new Map()
+    const marker = `${prefix}_filter_`
+    for (const [key, value] of params) {
+      if (!key.startsWith(marker)) continue
+      const dimension = key.slice(marker.length)
+      if (dimension) dimensions.set(dimension, value)
+    }
+    return dimensions
+  }
+}

data/app/assets/stylesheets/stimulus_table_filter/table_filter.css

@@ -0,0 +1,8 @@
+/* Required by the JS controller for row/group visibility toggling.
+   Scoped to the controller so the widget doesn't define a global utility class. */
+[data-controller="table-filter"] .hidden { display: none; }
+
+[data-sort-btn] {
+  cursor: pointer;
+  user-select: none;
+}

data/config/importmap.rb

@@ -0,0 +1,2 @@
+pin_all_from File.expand_path('../app/assets/javascripts/stimulus_table_filter', __dir__),
+             under: 'stimulus_table_filter', to: 'stimulus_table_filter'

data/eslint.config.js

@@ -0,0 +1,18 @@
+import js from "@eslint/js"
+import globals from "globals"
+
+export default [
+  { ignores: ["vendor/**", "node_modules/**", "coverage/**", "gemfiles/**", "tmp/**"] },
+  {
+    files: ["app/assets/javascripts/**/*.js", "test/javascript/**/*.mjs", "eslint.config.js"],
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: "module",
+      globals: { ...globals.browser, ...globals.node }
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      "no-unused-vars": ["error", { varsIgnorePattern: "^_", argsIgnorePattern: "^_" }]
+    }
+  }
+]

data/lib/spec/shared_examples/table_filter_footer.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples 'a table filter footer' do
+  it('has a match count target') { expect(html).to have_data_target('matchCount') }
+  it('has a total count target') { expect(html).to have_data_target('totalCount') }
+end

data/lib/spec/shared_examples/table_filter_rows.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples 'table filter row named' do |name|
+  it("has a filterable row for '#{name}'") { expect(html).to have_data('name', name) }
+end
+
+RSpec.shared_examples 'table filter rows with status' do |status|
+  it("has at least one row with status '#{status}'") { expect(html).to have_data('filter-status', status) }
+end
+
+RSpec.shared_examples 'table filter rows include names' do |*names|
+  names.each { |name| it_behaves_like 'table filter row named', name }
+end

data/lib/spec/shared_examples/table_filter_view.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples 'a table filter view' do
+  it('has a table-filter controller') { expect(html).to have_data('controller', 'table-filter') }
+  it('has a search input target') { expect(html).to have_data_target('search') }
+  it('has at least one filterable row') { expect(html).to have_data_target('row') }
+  it('has filter status buttons') { expect(html).to have_data('filter-btn') }
+  it('has sort buttons') { expect(html).to have_data('sort-btn') }
+end
+
+RSpec.shared_examples 'a table filter with sortable th headers' do
+  it('uses th elements as sort triggers') { expect(html).to have_data('sort-btn').on('th') }
+end
+
+RSpec.shared_examples 'a table filter with sort column' do |col|
+  it("has a sort trigger for column '#{col}'") { expect(html).to have_data('sort-btn', col) }
+end
+
+RSpec.shared_examples 'a table filter with empty row' do
+  it('has an empty-state row target') { expect(html).to have_data_target('emptyRow') }
+end
+
+RSpec.shared_examples 'a table filter with pagination controls' do
+  it('has a prev page button') { expect(html).to have_data('prev-page') }
+  it('has a next page button') { expect(html).to have_data('next-page') }
+  it('has a page info target') { expect(html).to have_data_target('pageInfo') }
+end
+
+RSpec.shared_examples 'a table filter with group headers' do
+  it('has a groupHeader target') { expect(html).to have_data_target('groupHeader') }
+end
+
+RSpec.shared_examples 'a table filter with group' do |group|
+  it("has rows in group '#{group}'") { expect(html).to have_data('group', group) }
+end
+
+RSpec.shared_examples 'a table filter with filter select' do
+  it('has a filterSelect target') { expect(html).to have_data_target('filterSelect') }
+end
+
+RSpec.shared_examples 'a table filter with filter display' do
+  it('has a filterDisplay target') { expect(html).to have_data_target('filterDisplay') }
+end
+
+RSpec.shared_examples 'a table filter with initial sort' do |col, dir: 'asc'|
+  it("has sort-value '#{col}'") { expect(html).to have_data('table-filter-sort-value', col) }
+  it("has dir-value '#{dir}'") { expect(html).to have_data('table-filter-dir-value', dir) }
+end
+
+RSpec.shared_examples 'a table filter with page size' do |n|
+  it("has page-size-value '#{n}'") { expect(html).to have_data('table-filter-page-size-value', n) }
+end
+
+RSpec.shared_examples 'a table filter with url key' do |key|
+  it("has url-key-value '#{key}'") { expect(html).to have_data('table-filter-url-key-value', key) }
+end
+
+RSpec.shared_examples 'a table filter with debounce' do |ms|
+  it("has debounce-ms-value '#{ms}'") { expect(html).to have_data('table-filter-debounce-ms-value', ms) }
+end
+
+RSpec.shared_examples 'a table filter with count' do |dimension, value|
+  it("has a count for #{dimension} '#{value}'") {
+    expect(html).to have_data('count-dimension', dimension).and have_data('count-value', value)
+  }
+end
+
+RSpec.shared_examples 'a table filter with filter btn' do |value|
+  it("has a filter button for '#{value}'") { expect(html).to have_data('filter-btn', value) }
+end
+
+RSpec.shared_examples 'a table filter with sort type' do |col, type|
+  it("sort trigger '#{col}' has type '#{type}'") {
+    expect(html).to have_data('sort-btn', col).and have_data('sort-type', type)
+  }
+end
+
+RSpec.shared_examples 'a table filter row with sort column' do |col|
+  it("rows have data-sort-#{col} attribute") { expect(html).to have_data("sort-#{col}") }
+end
+
+RSpec.shared_examples 'a table filter with accessible sort headers' do
+  let(:sortable_ths) { Nokogiri::HTML.fragment(html).css('th[data-sort-btn]') }
+
+  it('has th elements as sort triggers') { expect(sortable_ths).not_to be_empty }
+  it('sort th triggers have scope="col"') { expect(sortable_ths.map { |th| th['scope'] }).to all(eq('col')) }
+end

data/lib/stimulus_table_filter/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module StimulusTableFilter
+  class Engine < ::Rails::Engine
+    initializer 'stimulus_table_filter.helpers' do
+      ActiveSupport.on_load(:action_view) { include StimulusTableFilter::ViewHelper }
+    end
+
+    initializer 'stimulus_table_filter.assets' do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join('app/assets/javascripts')
+        app.config.assets.paths << root.join('app/assets/stylesheets')
+      end
+    end
+
+    initializer 'stimulus_table_filter.importmap', before: 'importmap' do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join('config/importmap.rb')
+        app.config.importmap.cache_sweepers << root.join('app/assets/javascripts')
+      end
+    end
+  end
+end

data/lib/stimulus_table_filter/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StimulusTableFilter
+  class Error < StandardError; end
+end