rokaki 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8fb8c022307112af51183df513130d6ad467142320a4db9be178870583c2394
-  data.tar.gz: 611539f7d9500f30c5a847a89a7548119c14d4eac47761e9c08b5e706ae9f77c
+  metadata.gz: 2659a359499939511a45107cc281e2aecce654ecf587f668e9de52d6fd8e3424
+  data.tar.gz: 4a5dfa2b6eef83fb731bb558575bdd5072b2c5ff2f4dc3670b11cae9487447ff
 SHA512:
-  metadata.gz: 3648caca4052f03440da996d1aed083c3ba9a29a5f14f06e9e9b2757d4d95f3356e793e22f1b1ebe0a149536a001367e6006d26d8521ce518885e32c36502130
-  data.tar.gz: ca064a797447597677bd5b2d2e00f6a2836bc5e69341990ac7da0742ccdc41383834f7a8c9bb6c4089a37e0293786c2536727b5c79d1dabf05a4c9df20f02b77
+  metadata.gz: a120036a6621d1ca69631d95fccd5fa3fac82cbb4a630bffcc5a5ea87ec026ef416fda109964eec929d1c8874af7a4dc08e06bab2cd1789779332ae9796b645e
+  data.tar.gz: 656df3353ae9593cdeaa75ce0b0111728fbbb420d8c4885928fcc334369ceaa07ea09f78a49b93b3ab45ea8d5767b81f9280cd9cf55260690a0a34270947c7ab

data/.github/workflows/pages.yml

@@ -0,0 +1,31 @@
+name: Build documentation (no deploy)
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_GEMFILE: docs/Gemfile
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3.0'
+          bundler-cache: true
+
+      - name: Build site
+        run: |
+          bundle exec jekyll build -s docs -d _site
+
+      - name: Upload built site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: _site

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+### 0.13.0 — 2025-10-25
+- Add block-form DSL parity across both FilterModel and Filterable (`filter_map do ... end` with `like`, `ilike`, `nested`, and `filters`).
+- Support circumfix affix synonyms: `:parafix`, `:confix`, `:ambifix` (treated as `:circumfix`).
+- Improve docs with block-form examples and adapter behavior notes.
+- Keep SQL Server support (introduced earlier) covered in CI; add shared tests for affix synonyms to all adapter-aware specs.
+- Allow ENV overrides for all adapters in test DatabaseManager (Postgres/MySQL/SQL Server).
+
+### 0.12.0 — 2025-10-25
+- Introduce block-form DSL for FilterModel (`filter_map do ... end`) with `like` and `nested`.
+- Update docs site and GitHub Pages build.
+
+### 0.11.0 — 2025-10-25
+- Add first-class SQL Server support.
+- CI updates to run tests against SQL Server, alongside PostgreSQL and MySQL.
+
+### 0.10.0 and earlier
+- Core DSL: Filterable and FilterModel modes, LIKE matching with prefix/suffix/circumfix, nested filters, and adapter-aware SQL for Postgres/MySQL.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rokaki (0.11.0)
+    rokaki (0.13.0)
       activesupport
 
 GEM

data/docs/Gemfile

@@ -0,0 +1,17 @@
+# docs/Gemfile
+source "https://rubygems.org"
+
+# Static site generator
+gem "jekyll", "~> 4.4"
+
+# Theme used by docs/_config.yml
+gem "minima", "~> 2.5"
+
+# GitHub-flavored Markdown support
+gem "kramdown-parser-gfm", "~> 1.1"
+
+# Ruby 3+ local serving requires webrick
+gem "webrick", "~> 1.8"
+
+# Ensure compatibility with workflow expectation
+gem "rake", "~> 13.3"

data/docs/_config.yml

@@ -0,0 +1,26 @@
+title: Rokaki
+description: A DSL for filtering data in web requests (ActiveRecord)
+# For project pages (https://<user>.github.io/<repo>), set:
+#   url: "https://tevio.github.io"
+#   baseurl: "/rokaki"
+# This ensures theme assets like /assets/main.css resolve under /rokaki/ on GitHub Pages.
+baseurl: "/rokaki"
+url: "https://tevio.github.io"
+theme: minima
+
+# Build settings
+markdown: kramdown
+kramdown:
+  input: GFM
+
+# Exclude existing generated RDoc folder from site
+exclude:
+  - doc/
+  - pkg/
+  - spec/
+  - Gemfile
+  - Gemfile.lock
+  - Rakefile
+  - rokaki.gemspec
+  - Guardfile
+  - README.md

data/docs/adapters.md

@@ -0,0 +1,46 @@
+---
+layout: page
+title: Database adapters
+permalink: /adapters
+---
+
+Rokaki generates adapter‑aware SQL for PostgreSQL, MySQL, and SQL Server.
+
+## Overview
+
+- PostgreSQL
+  - Case‑insensitive: `ILIKE`
+  - Case‑sensitive: `LIKE`
+  - Multi‑term: `ANY (ARRAY[...])`
+- MySQL
+  - Case‑insensitive: `LIKE`
+  - Case‑sensitive: `LIKE BINARY`
+  - Nested‑like filters may use `REGEXP` where designed in the library
+- SQL Server
+  - Uses `LIKE` with safe escaping
+  - Multi‑term input expands to OR‑chained predicates (e.g., `(col LIKE :q0 OR col LIKE :q1 ...)`) with `ESCAPE '\\'`
+  - Case sensitivity follows DB collation by default; future versions may add inline `COLLATE` options
+
+## LIKE modes
+
+All adapters support the same modes, which you declare via the values in your `like` mapping (there is no `modes:` option):
+
+- `prefix` → `%term`
+- `suffix` → `term%`
+- `circumfix` → `%term%` (synonyms supported: `:parafix`, `:confix`, `:ambifix`)
+
+Example:
+
+```ruby
+# Declare modes via like-mapping values (no block DSL)
+like title: :circumfix
+like author: { first_name: :prefix }
+```
+
+When you pass an array of terms, Rokaki composes adapter‑appropriate SQL that matches any of the terms.
+
+## Notes on case sensitivity
+
+- PostgreSQL: `ILIKE` is case‑insensitive; `LIKE` is case‑sensitive depending on collation/LC settings but generally treated as case‑sensitive for ASCII.
+- MySQL: `LIKE` case sensitivity depends on column collation; `LIKE BINARY` forces byte comparison (case‑sensitive for ASCII).
+- SQL Server: The server/database/column collation determines sensitivity. Rokaki currently defers to your DB’s default. If you need deterministic behavior regardless of DB defaults, consider using a case‑sensitive collation on the column or open an issue to discuss inline `COLLATE` options.

data/docs/configuration.md

@@ -0,0 +1,63 @@
+---
+layout: page
+title: Configuration
+permalink: /configuration
+---
+
+This page covers configuration, environment overrides, and tips for running the test suite across adapters.
+
+## Environment variables
+
+Rokaki's test helpers (used in the specs) support environment variable overrides for all adapters. These are useful when your local databases run on non‑default ports or hosts.
+
+### SQL Server
+- `SQLSERVER_HOST` (default: `localhost`)
+- `SQLSERVER_PORT` (default: `1433`)
+- `SQLSERVER_USERNAME` (default: `sa`)
+- `SQLSERVER_PASSWORD`
+- `SQLSERVER_DATABASE` (default: `rokaki`)
+
+### MySQL
+- `MYSQL_HOST` (default: `127.0.0.1`)
+- `MYSQL_PORT` (default: `3306`)
+- `MYSQL_USERNAME` (default: `rokaki`)
+- `MYSQL_PASSWORD` (default: `rokaki`)
+- `MYSQL_DATABASE` (default: `rokaki`)
+
+### PostgreSQL
+- `POSTGRES_HOST` (default: `127.0.0.1`)
+- `POSTGRES_PORT` (default: `5432`)
+- `POSTGRES_USERNAME` (default: `postgres`)
+- `POSTGRES_PASSWORD` (default: `postgres`)
+- `POSTGRES_DATABASE` (default: `rokaki`)
+
+## SQL Server notes
+
+- Rokaki uses `LIKE` with proper escaping and OR expansion for arrays of terms.
+- Case sensitivity follows your database/column collation. Future versions may allow inline `COLLATE` options.
+
+## Running tests locally
+
+Ensure you have Ruby (see `.ruby-version`), then install dependencies and run specs.
+
+```bash
+bundle install
+./spec/ordered_run.sh
+```
+
+Or run a single adapter suite, for example SQL Server:
+
+```bash
+bundle exec rspec spec/lib/03_sqlserver_aware_spec.rb
+```
+
+If your SQL Server listens on a different port (e.g., 1434), set an override:
+
+```bash
+export SQLSERVER_PORT=1434
+bundle exec rspec spec/lib/03_sqlserver_aware_spec.rb
+```
+
+## GitHub Actions
+
+The repository includes CI that starts MySQL (9.4), PostgreSQL (13), and SQL Server (2022) services and runs the ordered spec suite. See `.github/workflows/spec.yml`.

data/docs/index.md

@@ -0,0 +1,113 @@
+---
+layout: home
+title: Rokaki
+permalink: /
+---
+
+Rokaki is a small Ruby library that helps you build safe, composable filters for ActiveRecord queries in web requests.
+
+- Works with PostgreSQL, MySQL, and SQL Server
+- Supports simple and nested filters
+- LIKE-based matching with prefix/suffix/circumfix modes (circumfix also accepts synonyms: parafix, confix, ambifix)
+- Array-of-terms matching (adapter-aware)
+
+Get started below or jump to:
+- [Usage](./usage)
+- [Database adapters](./adapters)
+- [Configuration](./configuration)
+
+## Installation
+
+Add to your application's Gemfile:
+
+```ruby
+gem "rokaki", "~> 0.13"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Quick start
+
+You can declare mappings in two ways: argument-based (original) or block-form DSL. Both are equivalent.
+
+Argument-based form:
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  # Tell Rokaki which model to query and which DB adapter semantics to use
+  filter_model :article, db: :postgres # or :mysql, :sqlserver
+
+  # Map a single query key (:q) to multiple LIKE targets on Article
+  define_query_key :q
+  like title: :circumfix, content: :circumfix
+
+  # Nested LIKEs on associated models are expressed with hashes
+  like author: { first_name: :prefix, last_name: :suffix }
+
+  attr_accessor :filters
+  def initialize(filters: {})
+    @filters = filters
+  end
+end
+
+# In a controller/service:
+filtered = ArticleQuery.new(filters: params).results
+```
+
+Block-form DSL (same behavior):
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  filter_model :article, db: :postgres # or :mysql, :sqlserver
+  define_query_key :q
+
+  filter_map do
+    like title: :circumfix, content: :circumfix
+    nested :author do
+      like first_name: :prefix, last_name: :suffix
+      # You can also declare equality filters inside nested contexts
+      filters :id
+    end
+  end
+
+  attr_accessor :filters
+  def initialize(filters: {})
+    @filters = filters
+  end
+end
+
+# In a controller/service:
+filtered = ArticleQuery.new(filters: params).results
+```
+
+Where `params` can include keys like `q`, `author_first_name`, `author_last_name`, etc. The LIKE mode for each key is defined in your `like` mapping (e.g., `title: :circumfix`), and Rokaki builds the appropriate `WHERE` clauses safely and adapter‑aware.
+
+## Matching modes
+
+- prefix: matches values that start with given term(s)
+- suffix: matches values that end with given term(s)
+- circumfix: matches values that contain given term(s)
+
+All modes accept either a single string or an array of terms.
+
+## What’s new in 0.13.0
+
+- Block-form DSL parity across both FilterModel and Filterable
+- Circumfix affix synonyms supported: :parafix, :confix, :ambifix
+- SQL Server adapter support and CI coverage
+- ENV overrides for all adapters in test helpers; improved DB bootstrap in specs
+- Documentation site via GitHub Pages
+
+## Next steps
+
+- Learn the full DSL and examples in [Usage](./usage)
+- See adapter specifics (PostgreSQL/MySQL/SQL Server) in [Database adapters](./adapters)
+- Configure connections and environment variables in [Configuration](./configuration)

data/docs/usage.md

@@ -0,0 +1,188 @@
+---
+layout: page
+title: Usage
+permalink: /usage
+---
+
+This page shows how to use Rokaki to define filters and apply them to ActiveRecord relations.
+
+## Installation
+
+Add the gem to your Gemfile and bundle:
+
+```ruby
+gem "rokaki", "~> 0.13"
+```
+
+```bash
+bundle install
+```
+
+## Basic setup
+
+Include `Rokaki::Filterable` in models you want to filter, and define a `filter_map` with fields and nested associations.
+
+```ruby
+class Author < ActiveRecord::Base
+  has_many :articles
+end
+
+class ArticleQuery
+  include Rokaki::FilterModel
+  belongs_to :author
+
+  # Choose model and adapter
+  filter_model :article, db: :postgres # or :mysql, :sqlserver
+
+  # Map a single query key (:q) to multiple LIKE targets
+  define_query_key :q
+  like title: :circumfix, content: :circumfix
+
+  # Nested LIKEs via hash mapping
+  like author: { first_name: :prefix, last_name: :suffix }
+end
+```
+
+## Applying filters
+
+Call `Model.filter(params)` to build a relation based on supported keys.
+
+```ruby
+params = {
+  title_prefix: "Intro",
+  q: ["ruby", "rails"],
+  author_last_name: "martin"
+}
+
+filtered = Article.filter(params)
+# => ActiveRecord::Relation (chainable)
+```
+
+You can keep chaining other scopes/clauses:
+
+```ruby
+Article.filter(params).order(published: :desc).limit(20)
+```
+
+## LIKE modes and affix options
+
+Declare the LIKE mode via the value in your `like` mapping (there is no `modes:` option). For example: `like title: :prefix`.
+
+- `prefix` → matches strings that start with a term (pattern: `%term`)
+- `suffix` → matches strings that end with a term (pattern: `term%`)
+- `circumfix` → matches strings that contain a term (pattern: `%term%`)
+  - Synonyms supported: `:parafix`, `:confix`, `:ambifix` (all behave the same as `:circumfix`)
+
+Each accepts a single string or an array of strings. Rokaki generates adapter‑aware SQL:
+
+- PostgreSQL: `LIKE`/`ILIKE` with `ANY (ARRAY[...])`
+- MySQL: `LIKE`/`LIKE BINARY` and, in nested-like contexts, `REGEXP` where designed
+- SQL Server: `LIKE` with safe escaping; arrays expand into OR chains of parameterized `LIKE` predicates
+
+## Nested filters
+
+Use `nested :association` to scope filters to joined tables. Rokaki handles the necessary joins and qualified columns.
+
+```ruby
+filter_map do
+  nested :author do
+    like :first_name, key: :author_first
+  end
+end
+```
+
+Params would include `author_first`, `author_first_prefix`, etc.
+
+## Customization tips
+
+- Use `key:` to map a filter to a different params key.
+- Combine multiple filters; Rokaki composes them with `AND` by default.
+- For advanced cases, write custom filters in your app by extending the DSL (see source for `BasicFilter`/`NestedFilter`).
+
+
+## Block-form DSL
+
+Note: The block-form DSL is available starting in Rokaki 0.13.0.
+
+Rokaki also supports a block-form DSL that is equivalent to the argument-based form. Use it when you prefer grouping your mappings in a single block.
+
+### FilterModel block form
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  # Choose model and adapter
+  filter_model :article, db: :postgres # or :mysql, :sqlserver
+
+  # Declare a single query key used by all LIKE/equality filters below
+  define_query_key :q
+
+  # Declare mappings inside a block
+  filter_map do
+    # LIKE mappings on the base model
+    like title: :circumfix, content: :circumfix
+
+    # Nested mappings on associations
+    nested :author do
+      like first_name: :prefix, last_name: :suffix
+
+      # You can also declare equality filters in block form
+      filters :id
+    end
+  end
+
+  attr_accessor :filters
+  def initialize(filters: {})
+    @filters = filters
+  end
+end
+
+# Usage
+ArticleQuery.new(filters: { q: ["Intro", "Guide"] }).results
+```
+
+Notes:
+- Modes are declared by the values in your `like` mapping (`:prefix`, `:suffix`, `:circumfix`). Synonyms `:parafix`, `:confix`, `:ambifix` behave like `:circumfix`.
+- Arrays for `q` are supported across adapters. PostgreSQL uses `ANY (ARRAY[...])`, MySQL/SQL Server expand to OR chains as appropriate.
+
+### Filterable block form
+
+Use the block form to define simple key accessors (no SQL). Useful for plain Ruby objects or when building a mapping layer.
+
+```ruby
+class ArticleFilters
+  include Rokaki::Filterable
+  filter_key_prefix :__
+
+  filter_map do
+    filters :date, author: [:first_name, :last_name]
+
+    nested :author do
+      nested :location do
+        filters :city
+      end
+    end
+  end
+
+  # Expect a #filters method that returns a hash
+  attr_reader :filters
+  def initialize(filters: {})
+    @filters = filters
+  end
+end
+
+f = ArticleFilters.new(filters: {
+  date: '2025-01-01',
+  author: { first_name: 'Ada', last_name: 'Lovelace', location: { city: 'London' } }
+})
+
+f.__date                        # => '2025-01-01'
+f.__author__first_name          # => 'Ada'
+f.__author__last_name           # => 'Lovelace'
+f.__author__location__city      # => 'London'
+```
+
+Tips:
+- `filter_key_prefix` and `filter_key_infix` control the generated accessor names.
+- Inside the block, `nested :association` affects all `filters` declared within it.

data/lib/rokaki/filter_model.rb

@@ -103,7 +103,89 @@ module Rokaki
 
       private
 
-      def filter_map(model, query_key, options)
+      def normalize_like_modes(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), h|
+            h[k] = normalize_like_modes(v)
+          end
+        when Array
+          obj.map { |e| normalize_like_modes(e) }
+        when Symbol
+          # Treat alternative affixes as circumfix
+          return :circumfix if [:parafix, :confix, :ambifix].include?(obj)
+          obj
+        else
+          obj
+        end
+      end
+
+      # Merge two nested like/ilike mappings
+      def deep_merge_like(a, b)
+        return b if a.nil? || a == {}
+        return a if b.nil? || b == {}
+        a.merge(b) do |_, v1, v2|
+          if v1.is_a?(Hash) && v2.is_a?(Hash)
+            deep_merge_like(v1, v2)
+          else
+            # Prefer later definitions
+            v2
+          end
+        end
+      end
+
+      # Wrap a normalized mapping with current nested context stack
+      def wrap_in_context(mapping)
+        return mapping if !@__ctx_stack || @__ctx_stack.empty?
+        @__ctx_stack.reverse.inject(mapping) { |acc, key| { key => acc } }
+      end
+
+      # Block DSL: nested context for like/ilike within filter_map block
+      def nested(name, &blk)
+        if instance_variable_defined?(:@__in_filter_map_block) && @__in_filter_map_block
+          raise ArgumentError, 'nested requires a symbol name' unless name.is_a?(Symbol)
+          @__ctx_stack << name
+          instance_eval(&blk) if blk
+          @__ctx_stack.pop
+        else
+          raise NoMethodError, 'nested can only be used inside filter_map block'
+        end
+      end
+
+      def filter_map(*args, &block)
+        # Block form: requires prior calls to filter_model and define_query_key
+        if block_given? && args.empty?
+          raise ArgumentError, 'define_query_key must be called before block filter_map' unless @filter_map_query_key
+          raise ArgumentError, 'filter_model must be called before block filter_map' unless @model
+          @_filter_db ||= :postgres
+
+          # Enter block-collection mode
+          @__in_filter_map_block = true
+          @__block_like_accumulator = {}
+          @__block_ilike_accumulator = {}
+          @__ctx_stack = []
+
+          instance_eval(&block)
+
+          # Exit and materialize definitions
+          @__in_filter_map_block = false
+          unless @__block_like_accumulator.empty?
+            like(@__block_like_accumulator)
+          end
+          unless @__block_ilike_accumulator.empty?
+            ilike(@__block_ilike_accumulator)
+          end
+
+          # cleanup
+          @__block_like_accumulator = nil
+          @__block_ilike_accumulator = nil
+          @__ctx_stack = nil
+
+          return
+        end
+
+        # Positional/legacy form
+        model, query_key, options = args
         filter_model(model)
         @filter_map_query_key = query_key
 
@@ -126,6 +208,12 @@ module Rokaki
       end
 
       def filters(*filter_keys)
+        # In block form for FilterModel, allow equality filters inside nested contexts
+        if instance_variable_defined?(:@__in_filter_map_block) && @__in_filter_map_block
+          wrapped_keys = filter_keys.map { |fk| wrap_in_context(fk) }
+          filter_keys = wrapped_keys
+        end
+
         if @filter_map_query_key
           define_filter_map(@filter_map_query_key, *filter_keys)
         else
@@ -259,17 +347,31 @@ module Rokaki
 
       def like(args)
         raise ArgumentError, 'argument mush be a hash' unless args.is_a? Hash
-        @_like_semantics = (@_like_semantics || {}).merge(args)
+        if instance_variable_defined?(:@__in_filter_map_block) && @__in_filter_map_block
+          normalized = normalize_like_modes(args)
+          @__block_like_accumulator = deep_merge_like(@__block_like_accumulator, wrap_in_context(normalized))
+          return
+        end
+
+        normalized = normalize_like_modes(args)
+        @_like_semantics = (@_like_semantics || {}).merge(normalized)
 
-        like_keys = LikeKeys.new(args)
+        like_keys = LikeKeys.new(normalized)
         like_filters(like_keys, term_type: case_sensitive)
       end
 
       def ilike(args)
         raise ArgumentError, 'argument mush be a hash' unless args.is_a? Hash
-        @i_like_semantics = (@i_like_semantics || {}).merge(args)
+        if instance_variable_defined?(:@__in_filter_map_block) && @__in_filter_map_block
+          normalized = normalize_like_modes(args)
+          @__block_ilike_accumulator = deep_merge_like(@__block_ilike_accumulator, wrap_in_context(normalized))
+          return
+        end
+
+        normalized = normalize_like_modes(args)
+        @i_like_semantics = (@i_like_semantics || {}).merge(normalized)
 
-        like_keys = LikeKeys.new(args)
+        like_keys = LikeKeys.new(normalized)
         like_filters(like_keys, term_type: case_insensitive)
       end
 

data/lib/rokaki/filterable.rb

@@ -13,6 +13,48 @@ module Rokaki
     module ClassMethods
       private
 
+      # --- Block DSL support (Filterable mode) ---
+      def nested(name, &blk)
+        if instance_variable_defined?(:@__in_filterable_block) && @__in_filterable_block
+          raise ArgumentError, 'nested requires a symbol name' unless name.is_a?(Symbol)
+          @__ctx_stack << name
+          instance_eval(&blk) if blk
+          @__ctx_stack.pop
+        else
+          raise NoMethodError, 'nested can only be used inside filter_map block'
+        end
+      end
+
+      # In Filterable, `filter_map` without args opens a block to declare `filters` with optional nesting
+      # For backward compatibility, if args are provided, delegate to define_filter_map
+      def filter_map(*args, &block)
+        if block_given? && args.empty?
+          # Enter block-collection mode
+          @__in_filterable_block = true
+          @__ctx_stack = []
+          @__block_filters = []
+
+          instance_eval(&block)
+
+          # Materialize collected filters
+          unless @__block_filters.empty?
+            define_filter_keys(*@__block_filters)
+          end
+
+          # cleanup
+          @__in_filterable_block = false
+          @__ctx_stack = nil
+          @__block_filters = nil
+          return
+        end
+
+        # Positional/legacy map form (delegates to define_filter_map)
+        if args.any?
+          query_field, *filter_keys = args
+          define_filter_map(query_field, *filter_keys)
+        end
+      end
+
       def define_filter_keys(*filter_keys)
         filter_keys.each do |filter_key|
           _build_filter([filter_key]) unless Hash === filter_key
@@ -96,8 +138,8 @@ module Rokaki
         if value.is_a? Array
           value.each do |av|
             if av.is_a? Symbol
-            _keys = keys.dup << av
-            yield _keys
+              _keys = keys.dup << av
+              yield _keys
             else
               deep_map(keys, av, &block)
             end
@@ -110,6 +152,33 @@ module Rokaki
         end
       end
 
+      # Helper: wrap a Symbol/Hash filter key in current nested context
+      def wrap_in_context(filter_key)
+        return filter_key unless instance_variable_defined?(:@__ctx_stack) && @__ctx_stack && !@__ctx_stack.empty?
+        ctx = @__ctx_stack.dup
+        if filter_key.is_a?(Hash)
+          # Nest the entire hash under the context chain
+          ctx.reverse.inject(filter_key) { |acc, k| { k => acc } }
+        else
+          # Symbol → build a hash with leaf
+          ctx.reverse.inject(filter_key) { |acc, k| { k => acc } }
+        end
+      end
+
+      public
+
+      # Enhance `filters` to support block mode accumulation
+      def filters(*filter_keys)
+        if instance_variable_defined?(:@__in_filterable_block) && @__in_filterable_block
+          filter_keys.each do |fk|
+            @__block_filters << wrap_in_context(fk)
+          end
+          return
+        end
+
+        define_filter_keys(*filter_keys)
+      end
+
     end
 
     def filters

data/lib/rokaki/version.rb

@@ -1,3 +1,3 @@
 module Rokaki
-  VERSION = "0.11.0"
+  VERSION = "0.13.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rokaki
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Steve Martin
@@ -242,11 +242,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/codeql-analysis.yml"
+- ".github/workflows/pages.yml"
 - ".github/workflows/spec.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - Guardfile
@@ -255,6 +257,12 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/Gemfile
+- docs/_config.yml
+- docs/adapters.md
+- docs/configuration.md
+- docs/index.md
+- docs/usage.md
 - lib/rokaki.rb
 - lib/rokaki/filter_model.rb
 - lib/rokaki/filter_model/basic_filter.rb