stimulus_table_filter 0.1.0

data/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "stimulus-table-filter",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "lint": "eslint .",
+    "test": "node --import ./test/javascript/register.mjs --test test/javascript/*.test.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0"
+  }
+}

data/stimulus_table_filter.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'stimulus_table_filter/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'stimulus_table_filter'
+  s.version     = StimulusTableFilter::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['icoluccio']
+  s.email       = ['ignacio.coluccio@gmail.com']
+  s.homepage    = 'https://github.com/icoluccio/stimulus-table-filter'
+  s.summary     = 'Client-side table filtering, sorting and search for Rails'
+  s.description = 'Stimulus controller and view helpers that add instant search, filter ' \
+                  'dimensions, multi-column sort, pagination and live footer stats to any ' \
+                  'Rails table. Everything is wired through data attributes, with no ' \
+                  'JavaScript dependencies or configuration required.'
+  s.license     = 'MIT'
+  s.required_ruby_version = '>= 3.2'
+
+  s.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.start_with?('spec/', 'gemfiles/', '.github/', 'coverage/', '.bundle/') ||
+      %w[Appraisals .overcommit.yml .rubocop.yml .gitignore Rakefile].include?(f)
+  end
+  s.require_paths = ['lib']
+
+  s.add_dependency 'railties', '>= 7.0', '< 9'
+end

data/test/javascript/controller.test.mjs

@@ -0,0 +1,10 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import controller from '../../app/assets/javascripts/stimulus_table_filter/table_filter_controller.js'
+import { TableView } from '../../app/assets/javascripts/stimulus_table_filter/table_filter_view.js'
+
+test('the controller and view modules load with their full import graphs', () => {
+  assert.equal(typeof controller, 'function')
+  assert.equal(controller.targets.length, 12)
+  assert.equal(typeof TableView, 'function')
+})

data/test/javascript/controller_stub.mjs

@@ -0,0 +1 @@
+export class Controller {}

data/test/javascript/paginator.test.mjs

@@ -0,0 +1,35 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { Paginator } from '../../app/assets/javascripts/stimulus_table_filter/paginator.js'
+
+const PAGE_SIZE = 25
+const TOTAL = 87
+const LAST_PAGE = 4   // ceil(87 / 25)
+const paginator = (size = PAGE_SIZE) => new Paginator(size)
+
+test('is disabled when the page size is 0 or missing', () => {
+  assert.equal(paginator(0).enabled, false)
+  assert.equal(new Paginator(undefined).enabled, false)
+})
+
+test('page count rounds up and never returns zero', () => {
+  assert.equal(paginator().pageCount(TOTAL), LAST_PAGE)
+  assert.equal(paginator().pageCount(PAGE_SIZE), 1)
+  assert.equal(paginator().pageCount(0), 1)
+})
+
+test('clamp caps the page at the last one with rows', () => {
+  assert.equal(paginator().clamp(99, TOTAL), LAST_PAGE)
+  assert.equal(paginator().clamp(2, TOTAL), 2)
+})
+
+test('window returns the slice bounds for a page', () => {
+  assert.deepEqual(paginator().window(3), { start: 50, end: 75 })
+  assert.deepEqual(paginator().window(1), { start: 0, end: PAGE_SIZE })
+})
+
+test('info formats the visible range for the matched rows', () => {
+  assert.equal(paginator().info(2, TOTAL), '26–50 of 87')
+  assert.equal(paginator().info(LAST_PAGE, TOTAL), '76–87 of 87')
+  assert.equal(paginator().info(1, 0), '')
+})

data/test/javascript/register.mjs

@@ -0,0 +1,20 @@
+import { registerHooks } from 'node:module'
+import { pathToFileURL } from 'node:url'
+
+// Maps the gem's importmap names and the Stimulus dependency to real files so
+// Node can load the browser modules directly.
+const MODULES = new URL('../../app/assets/javascripts/stimulus_table_filter/', import.meta.url)
+
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    if (specifier.startsWith('stimulus_table_filter/')) {
+      const name = specifier.slice('stimulus_table_filter/'.length)
+      return { shortCircuit: true, url: pathToFileURL(new URL(`${name}.js`, MODULES).pathname).href }
+    }
+    if (specifier === '@hotwired/stimulus') {
+      const stub = pathToFileURL(new URL('./controller_stub.mjs', import.meta.url).pathname).href
+      return { shortCircuit: true, url: stub }
+    }
+    return nextResolve(specifier, context)
+  }
+})

data/test/javascript/row_matcher.test.mjs

@@ -0,0 +1,71 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { RowMatcher } from '../../app/assets/javascripts/stimulus_table_filter/row_matcher.js'
+
+test('search matches data-name case-insensitively as a substring', () => {
+  const matcher = new RowMatcher('LPH', {})
+  assert.equal(matcher.matches({ dataset: { name: 'alpha' } }), true)
+  assert.equal(matcher.matches({ dataset: { name: 'beta' } }), false)
+})
+
+test('search prefers data-searchable over data-name', () => {
+  const matcher = new RowMatcher('tag', {})
+  assert.equal(matcher.matches({ dataset: { name: 'alpha', searchable: 'Alpha Tag' } }), true)
+  assert.equal(matcher.matches({ dataset: { name: 'alpha', searchable: 'Other' } }), false)
+})
+
+test('empty searchable falls back to data-name', () => {
+  const matcher = new RowMatcher('alpha', {})
+  assert.equal(matcher.matches({ dataset: { name: 'alpha', searchable: '' } }), true)
+})
+
+test('filter matches any value in the dimension list', () => {
+  const matcher = new RowMatcher('', { status: 'active,draft' })
+  assert.equal(matcher.matches({ dataset: { filterStatus: 'active' } }), true)
+  assert.equal(matcher.matches({ dataset: { filterStatus: 'draft' } }), true)
+  assert.equal(matcher.matches({ dataset: { filterStatus: 'archived' } }), false)
+})
+
+test('an "all" dimension value matches every row', () => {
+  const matcher = new RowMatcher('', { status: 'all' })
+  assert.equal(matcher.matches({ dataset: { filterStatus: 'anything' } }), true)
+})
+
+test('blank query and empty dimensions match every row', () => {
+  const matcher = new RowMatcher('   ', {})
+  assert.equal(matcher.matches({ dataset: { name: 'alpha', filterStatus: 'active' } }), true)
+})
+
+test('dimensions AND: the row must match every dimension with active values', () => {
+  const matcher = new RowMatcher('', { status: 'active', payment: 'paid' })
+  assert.equal(matcher.matches({ dataset: { filterStatus: 'active', filterPayment: 'paid' } }), true)
+  assert.equal(matcher.matches({ dataset: { filterStatus: 'active', filterPayment: 'unpaid' } }), false)
+  assert.equal(matcher.matches({ dataset: { filterStatus: 'archived', filterPayment: 'paid' } }), false)
+})
+
+test('rows without a value for an active dimension never match it', () => {
+  const matcher = new RowMatcher('', { payment: 'paid' })
+  assert.equal(matcher.matches({ dataset: {} }), false)
+})
+
+test('an "all" dimension value matches every row regardless of the row value', () => {
+  const matcher = new RowMatcher('', { payment: 'all' })
+  assert.equal(matcher.matches({ dataset: { filterPayment: 'whatever' } }), true)
+})
+
+test('toggledFilter replaces "all" with the clicked value', () => {
+  assert.equal(RowMatcher.toggledFilter('all', 'active'), 'active')
+})
+
+test('toggledFilter toggles values in and out of the active list', () => {
+  assert.equal(RowMatcher.toggledFilter('active', 'draft'), 'active,draft')
+  assert.equal(RowMatcher.toggledFilter('active,draft', 'draft'), 'active')
+})
+
+test('toggledFilter returns "all" when the last value is removed', () => {
+  assert.equal(RowMatcher.toggledFilter('active', 'active'), 'all')
+})
+
+test('toggledFilter resets to "all"', () => {
+  assert.equal(RowMatcher.toggledFilter('active,draft', 'all'), 'all')
+})

data/test/javascript/row_sorter.test.mjs

@@ -0,0 +1,43 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { RowSorter } from '../../app/assets/javascripts/stimulus_table_filter/row_sorter.js'
+
+// Sorts a single column through RowSorter and returns the values in sorted order.
+const sortColumn = (column, values, type = 'string', dir = 'asc') => {
+  const key = `sort${column.charAt(0).toUpperCase()}${column.slice(1)}`
+  const rows = values.map(value => ({ dataset: { [key]: value } }))
+  return new RowSorter(column, type, dir).sort(rows).map(r => r.dataset[key])
+}
+
+test('string sort compares lexicographically in the given direction', () => {
+  assert.deepEqual(sortColumn('title', ['b', 'a', 'c']), ['a', 'b', 'c'])
+  assert.deepEqual(sortColumn('title', ['b', 'a', 'c'], 'string', 'desc'), ['c', 'b', 'a'])
+})
+
+test('numeric sort orders numerically, not lexicographically', () => {
+  assert.deepEqual(sortColumn('amount', ['10', '2'], 'numeric'), ['2', '10'])
+})
+
+test('numeric sort puts missing values last in both directions', () => {
+  assert.deepEqual(sortColumn('amount', ['', '10', '2'], 'numeric'), ['2', '10', ''])
+  assert.deepEqual(sortColumn('amount', ['', '10', '2'], 'numeric', 'desc'), ['10', '2', ''])
+})
+
+test('numeric sort falls back to the plain column attribute', () => {
+  const rows = [{ dataset: { amount: '5' } }, { dataset: { amount: '1' } }]
+  const sorted = new RowSorter('amount', 'numeric', 'asc').sort(rows)
+  assert.deepEqual(sorted.map(r => r.dataset.amount), ['1', '5'])
+})
+
+test('date-dmy sorts by actual date and puts missing values last', () => {
+  const values = ['03/01/2024', '15/01/2024', '20/12/2023', '']
+  assert.deepEqual(sortColumn('created', values, 'date-dmy'), ['20/12/2023', '03/01/2024', '15/01/2024', ''])
+})
+
+test('date-mdy parses month-first dates', () => {
+  assert.deepEqual(sortColumn('created', ['01/15/2024', '01/03/2024'], 'date-mdy'), ['01/03/2024', '01/15/2024'])
+})
+
+test('ISO dates sort without an explicit type suffix', () => {
+  assert.deepEqual(sortColumn('created', ['2024-02-01', '2024-01-15'], 'date'), ['2024-01-15', '2024-02-01'])
+})

data/test/javascript/row_stats_and_url_state.test.mjs

@@ -0,0 +1,69 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { RowStats } from '../../app/assets/javascripts/stimulus_table_filter/row_stats.js'
+import { UrlState } from '../../app/assets/javascripts/stimulus_table_filter/url_state.js'
+
+const row = (status) => ({ dataset: { filterStatus: status } })
+
+test('computes matched and total counts over the filtered set', () => {
+  const rows = [row('active'), row('draft'), row('archived')]
+  const matchedRows = [rows[0], rows[1]]
+  assert.deepEqual(RowStats.compute(rows, matchedRows), { matched: 2, total: 3 })
+})
+
+test('percentage rounds to the nearest whole number and survives empty tables', () => {
+  assert.equal(RowStats.percentage(1, 3), 33)
+  assert.equal(RowStats.percentage(0, 0), 0)
+})
+
+const withLocation = (search, pathname = '/items') => {
+  globalThis.location = { search, pathname }
+  const urls = []
+  globalThis.history = { replaceState: (_state, _title, url) => urls.push(url) }
+  return urls
+}
+
+test('read returns present params and drops the rest', () => {
+  withLocation('?tf_sort=grade&tf_dir=desc')
+  assert.deepEqual(UrlState.read('tf'), { sort: 'grade', dir: 'desc' })
+})
+
+test('read collects per-dimension filter params', () => {
+  withLocation('?tf_filter_state=active&tf_filter_payment=paid')
+  assert.deepEqual(UrlState.read('tf'), { filterDimensions: { state: 'active', payment: 'paid' } })
+})
+
+test('read parses the page as an integer', () => {
+  withLocation('?tf_page=3')
+  assert.deepEqual(UrlState.read('tf'), { page: 3 })
+})
+
+test('write keeps params that differ from their defaults', () => {
+  const urls = withLocation('')
+  UrlState.write('tf', { filterDimensions: { state: 'active' }, sort: 'grade', dir: 'desc', search: 'bob', page: 2 })
+  assert.equal(urls[0], '/items?tf_sort=grade&tf_dir=desc&tf_page=2&tf_search=bob&tf_filter_state=active')
+})
+
+test('write drops params equal to their defaults and preserves foreign params', () => {
+  const urls = withLocation('?keep=1&tf_filter_state=active')
+  UrlState.write('tf', { filterDimensions: {}, sort: 'name', dir: 'asc', search: '', page: 1 })
+  assert.equal(urls[0], '/items?keep=1')
+})
+
+test('write serializes dimension filters as separate params', () => {
+  const urls = withLocation('')
+  UrlState.write('tf', {
+    filterDimensions: { state: 'active', payment: 'paid' },
+    sort: 'name', dir: 'asc', search: '', page: 1
+  })
+  assert.equal(urls[0], '/items?tf_filter_state=active&tf_filter_payment=paid')
+})
+
+test('write drops dimension params that are empty or all', () => {
+  const urls = withLocation('?tf_filter_state=active&tf_filter_payment=paid')
+  UrlState.write('tf', {
+    filterDimensions: { state: 'all', payment: '' },
+    sort: 'name', dir: 'asc', search: '', page: 1
+  })
+  assert.equal(urls[0], '/items?')
+})

data/test/javascript/stimulus_stub.mjs

@@ -0,0 +1,6 @@
+const stub = new URL('./controller_stub.mjs', import.meta.url).href
+
+export async function resolve(specifier, context, next) {
+  if (specifier === '@hotwired/stimulus') return { shortCircuit: true, url: stub }
+  return next(specifier, context)
+}

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: stimulus_table_filter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- icoluccio
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Stimulus controller and view helpers that add instant search, filter
+  dimensions, multi-column sort, pagination and live footer stats to any Rails table.
+  Everything is wired through data attributes, with no JavaScript dependencies or
+  configuration required.
+email:
+- ignacio.coluccio@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- app/assets/javascripts/stimulus_table_filter/filter_list.js
+- app/assets/javascripts/stimulus_table_filter/page_navigator.js
+- app/assets/javascripts/stimulus_table_filter/paginator.js
+- app/assets/javascripts/stimulus_table_filter/row_matcher.js
+- app/assets/javascripts/stimulus_table_filter/row_sorter.js
+- app/assets/javascripts/stimulus_table_filter/row_stats.js
+- app/assets/javascripts/stimulus_table_filter/table_filter.js
+- app/assets/javascripts/stimulus_table_filter/table_filter_controller.js
+- app/assets/javascripts/stimulus_table_filter/table_filter_view.js
+- app/assets/javascripts/stimulus_table_filter/url_state.js
+- app/assets/stylesheets/stimulus_table_filter/table_filter.css
+- config/importmap.rb
+- eslint.config.js
+- lib/spec/shared_examples/table_filter_footer.rb
+- lib/spec/shared_examples/table_filter_rows.rb
+- lib/spec/shared_examples/table_filter_view.rb
+- lib/stimulus_table_filter.rb
+- lib/stimulus_table_filter/engine.rb
+- lib/stimulus_table_filter/error.rb
+- lib/stimulus_table_filter/rspec.rb
+- lib/stimulus_table_filter/rspec/helpers.rb
+- lib/stimulus_table_filter/rspec/matchers.rb
+- lib/stimulus_table_filter/version.rb
+- lib/stimulus_table_filter/view_helper.rb
+- lib/stimulus_table_filter/view_helper/container.rb
+- lib/stimulus_table_filter/view_helper/controls.rb
+- lib/stimulus_table_filter/view_helper/rows.rb
+- lib/stimulus_table_filter/view_helper/sort.rb
+- lib/stimulus_table_filter/view_helper/stats.rb
+- package-lock.json
+- package.json
+- stimulus_table_filter.gemspec
+- test/javascript/controller.test.mjs
+- test/javascript/controller_stub.mjs
+- test/javascript/paginator.test.mjs
+- test/javascript/register.mjs
+- test/javascript/row_matcher.test.mjs
+- test/javascript/row_sorter.test.mjs
+- test/javascript/row_stats_and_url_state.test.mjs
+- test/javascript/stimulus_stub.mjs
+homepage: https://github.com/icoluccio/stimulus-table-filter
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Client-side table filtering, sorting and search for Rails
+test_files: []