yummy-guide-generic-administrate 0.5.4 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 387008d1b76513f348890946b449fcc46cdbb4ed61f594378786288baf0e74b7
-  data.tar.gz: 672c758ae345bcee1b7726e41bca7f6e7d77b9b5d2f52896ffd5514095d96cf6
+  metadata.gz: f3caffae44b6ea10fc063a2cc8fb8a3938e3cc42078c4af3bc2a08d4188cf01a
+  data.tar.gz: cea155304d262445a29199f9c5e57c574600508dca66206f49b81b3d3db66fb2
 SHA512:
-  metadata.gz: dbcf02d875cf41c10c080df757669320a22b9af01377848652445fac1ece7d1473f4c32f465c3c09a871702a3a77b3b28fc7883456f4b3ee25fa393566ab796f
-  data.tar.gz: 32b6e0fa25d8c7f5619c021be719cc28e74aa22c7c6f5a2220c0e5397d0589c52ffa26bdb9bb8e4d85213e8f342eb57fe0460ca7d6cc951b54ae552f24c39e1f
+  metadata.gz: 6a2e5a4b98e6cea96bfdc9e0cb026212c6ed37f39518800368329cc8ba1fcff202859acb8b3340754b493544b92f33e191d92606de032575c889e436ae39b789
+  data.tar.gz: 669b6a383ff6d184527e7324def8875626dc46dd0b5d9c5d55d3b5f18fd8f4e97188d6a943ffa65e4076a70eefd0389e41abbd7b77d97f9e98466a3c580ecc43

data/README.md

@@ -41,6 +41,8 @@ bundle install
   - 一覧テーブルの固定列数、リンク生成、action partial 解決を補助する helper
 - `YummyGuide::Administrate::FilterFormHelper`
   - datetime フィルターや checkbox group の組み立てを補助する helper
+- `YummyGuide::Administrate::FilterControlsHelper`
+  - dashboard の Field 型フィルター定義から Filter ボタンとモーダルフォームを描画する helper
 - `YummyGuide::Administrate::DatetimeInputHelper`
   - 管理画面フォーム用の date + time 入力 helper
 - `YummyGuide::Administrate::NumberInputHelper`
@@ -52,6 +54,7 @@ bundle install
   - `clipboards.js`
   - `datetime_input.js`
   - `fixed_submit_actions.js`
+  - `filter_controls.js`
   - `filter_form.js`
   - `sticky_left_columns.js`
   - `sticky_table_headers.js`
@@ -103,6 +106,7 @@ class Admin::ApplicationController < Administrate::ApplicationController
 
   helper YummyGuide::Administrate::CollectionHelper
   helper YummyGuide::Administrate::DatetimeInputHelper
+  helper YummyGuide::Administrate::FilterControlsHelper
   helper YummyGuide::Administrate::FilterFormHelper
   helper YummyGuide::Administrate::NumberInputHelper
 end
@@ -300,6 +304,140 @@ def search_term
 end
 ```
 
+### Dashboard driven filter controls
+
+dashboard に `FILTER_ATTRIBUTES` を定義すると、`admin_filter_controls` で既存の
+Administrate index header に Filter ボタンとモーダルフォームを描画できます。
+
+#### Filter の設定方法
+
+1. dashboard に送信先と filter 対象項目を定義します。
+
+```ruby
+class AdspendDashboard < ApplicationDashboard
+  FILTER_PATH = ->(view, _locals) { view.admin_adspends_path }
+  FILTER_CLEAR_PATH = ->(view, _locals) { view.admin_adspends_path }
+
+  FILTER_ATTRIBUTES = {
+    campaign_name: YummyGuide::Administrate::Filters::Text.with_options(label: "Campaign name"),
+    yearmonth: YummyGuide::Administrate::Filters::Text.with_options(
+      label: "Year month",
+      inputmode: "numeric",
+      pattern: "\\d{6}",
+      placeholder: "YYYYMM"
+    )
+  }.freeze
+end
+```
+
+2. index header などで `admin_filter_controls` を呼び出します。`page` から dashboard を
+   解決し、`FILTER_ATTRIBUTES` が存在する場合だけ Filter ボタンとフォームを描画します。
+
+```erb
+<%= admin_filter_controls(
+      page: page,
+      search_options: search_options
+    ) %>
+```
+
+送信先は helper の `path:` / `clear_path:` で明示することもできます。helper の指定は
+dashboard の `FILTER_PATH` / `FILTER_CLEAR_PATH` より優先されます。
+
+```erb
+<%= admin_filter_controls(
+      page: page,
+      path: admin_adspends_path,
+      clear_path: admin_adspends_path,
+      search_options: search_options,
+      filter_locals: { show_discarded_filter: false },
+      root_hidden_fields: { "reservation[order]" => current_order[:order] },
+      extra_actions: [button_tag("Download PDF", type: "button", class: "button")]
+    ) %>
+```
+
+標準 Field は `Text`, `Select`, `Checkbox`, `RadioGroup`, `CheckboxGroup`,
+`DateRange`, `DatetimeRange`, `DatetimeLocalRange`, `Custom` です。
+主な option は次のとおりです。
+
+- 共通: `label`, `default`, `if`, `class`, `id`, `placeholder`, `inputmode`, `pattern`
+- 選択系: `collection` または `options`, `select_options`
+- checkbox: `checked_value`, `unchecked_value`
+- checkbox group: `group`
+- range: `from`, `to`, `from_default`, `to_default`, `css_class`
+
+`label`, `collection`, `default`, `if` などの option には Proc も指定できます。Proc は
+arity に応じて `call`, `call(view_context)`, `call(view_context, filter_locals)` のいずれかで評価されます。
+
+```ruby
+FILTER_ATTRIBUTES = {
+  owner_id: YummyGuide::Administrate::Filters::Text.with_options(
+    label: "Owner ID",
+    inputmode: "numeric",
+    if: ->(view, _locals) { !view.current_user&.owner? }
+  ),
+  status: YummyGuide::Administrate::Filters::Select.with_options(
+    label: "Status",
+    collection: ->(_view, locals) { locals[:status_collection] },
+    select_options: { include_blank: true }
+  )
+}.freeze
+```
+
+#### カスタム Filter の作成方法
+
+既存の Field 型で表現できない場合は、partial を使う方法と独自クラスを定義する方法があります。
+
+partial だけで足りる場合は `Custom` を使います。partial には `form`, `form_scope`,
+`field`, `current_values`, `filter_locals` が渡されます。
+
+```ruby
+FILTER_ATTRIBUTES = {
+  price_range: YummyGuide::Administrate::Filters::Custom.with_options(
+    partial: "admin/filters/price_range"
+  )
+}.freeze
+```
+
+```erb
+<tr>
+  <td><%= form.label field.name, field.label_text(self, filter_locals) %></td>
+  <td>
+    <%= form.number_field :min_price, value: current_values["min_price"] %>
+    <%= form.number_field :max_price, value: current_values["max_price"] %>
+  </td>
+  <%= filter_field_clear_cell if respond_to?(:filter_field_clear_cell) %>
+</tr>
+```
+
+`filter_form.js` を読み込んでいる場合、`data-behavior="filter-field-clear"` を持つ
+button は同じ `tr` 内の input / select / textarea / checkbox / radio / datetime
+filter だけをクリアします。
+
+複数画面で再利用する filter 型は `YummyGuide::Administrate::Filters::Base` を継承して作ります。
+単一 input なら `input` を実装し、行全体を制御したい場合は `row` または `input_cell` を上書きします。
+
+```ruby
+class CurrencyFilter < YummyGuide::Administrate::Filters::Base
+  private
+
+  def input(view_context, form, current_values, locals)
+    form.select(
+      name,
+      view_context.options_for_select(options.fetch(:collection), current_value(current_values)),
+      { include_blank: true },
+      html_options(view_context, locals)
+    )
+  end
+end
+
+FILTER_ATTRIBUTES = {
+  payout_currency: CurrencyFilter.with_options(
+    label: "Currency",
+    collection: [["JPY", "JPY"], ["USD", "USD"]]
+  )
+}.freeze
+```
+
 ### Number input helper
 
 Admin/Administrate 画面では、`number_field` / `number_field_tag` を
@@ -321,6 +459,7 @@ Admin/Administrate 画面では、`number_field` / `number_field_tag` を
 //= require yummy_guide_administrate/clipboards
 //= require yummy_guide_administrate/datetime_input
 //= require yummy_guide_administrate/fixed_submit_actions
+//= require yummy_guide_administrate/filter_controls
 //= require yummy_guide_administrate/filter_form
 //= require yummy_guide_administrate/sticky_left_columns
 //= require yummy_guide_administrate/sticky_table_headers

data/app/assets/javascripts/yummy_guide_administrate/filter_controls.js

@@ -0,0 +1,30 @@
+(function() {
+  function initialize(root) {
+    var scope = root || document;
+    scope.querySelectorAll('[data-admin-filter-form="true"]').forEach(function(formEl) {
+      if (formEl.dataset.adminFilterControlsInitialized === 'true') return;
+
+      formEl.dataset.adminFilterControlsInitialized = 'true';
+
+      formEl.addEventListener('submit', function(event) {
+        if (formEl.dataset.submitMode !== 'event') return;
+
+        event.preventDefault();
+        document.dispatchEvent(new CustomEvent('yummy-guide:administrate-filter:submit', {
+          detail: {
+            form: formEl,
+            formData: new FormData(formEl)
+          }
+        }));
+      });
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function() { initialize(document); }, { once: true });
+  } else {
+    initialize(document);
+  }
+
+  document.addEventListener('turbo:load', function() { initialize(document); });
+})();

data/app/assets/javascripts/yummy_guide_administrate/filter_form.js

@@ -43,6 +43,12 @@
       });
     });
 
+    formEl.querySelectorAll('[data-behavior="filter-field-clear"]').forEach(function(buttonEl) {
+      buttonEl.addEventListener("click", function(event) {
+        clearFilterField(formEl, event);
+      });
+    });
+
     formEl.querySelectorAll('[data-behavior="checkbox-group-select-all"]').forEach(function(buttonEl) {
       buttonEl.addEventListener("click", function() {
         setCheckboxGroupState(formEl, buttonEl.dataset.target, true);
@@ -58,6 +64,19 @@
     syncDatetimeFilterFields(formEl);
   }
 
+  function clearFilterField(formEl, event) {
+    event.preventDefault();
+
+    var rowEl = event.currentTarget.closest("tr");
+    if (!rowEl) return;
+
+    clearTextControls(rowEl);
+    clearChoiceControls(rowEl);
+    clearSelectControls(rowEl);
+    clearDatetimeFilters(rowEl);
+    syncDatetimeFilterFields(formEl);
+  }
+
   function clearFormFields(formEl) {
     formEl.querySelectorAll("input, select, textarea").forEach(function(fieldEl) {
       if (fieldEl.disabled || fieldEl.type === "hidden" || fieldEl.type === "submit") {
@@ -86,6 +105,57 @@
     syncDatetimeFilterFields(formEl);
   }
 
+  function clearTextControls(rowEl) {
+    rowEl.querySelectorAll("input, textarea").forEach(function(inputEl) {
+      var inputType = (inputEl.getAttribute("type") || "").toLowerCase();
+
+      if (inputType === "checkbox" || inputType === "radio") return;
+      if (inputType === "hidden" && inputEl.dataset.datetimePart !== "combined") return;
+
+      inputEl.value = "";
+      inputEl.setAttribute("value", "");
+    });
+  }
+
+  function clearChoiceControls(rowEl) {
+    rowEl.querySelectorAll('input[type="checkbox"], input[type="radio"]').forEach(function(inputEl) {
+      inputEl.checked = false;
+    });
+  }
+
+  function clearSelectControls(rowEl) {
+    rowEl.querySelectorAll("select").forEach(function(selectEl) {
+      if (selectEl.querySelector('option[value=""]')) {
+        selectEl.value = "";
+      } else if (selectEl.querySelector('option[value="all"]')) {
+        selectEl.value = "all";
+      } else {
+        selectEl.selectedIndex = -1;
+      }
+    });
+  }
+
+  function clearDatetimeFilters(rowEl) {
+    rowEl.querySelectorAll("[data-datetime-filter]").forEach(function(groupEl) {
+      var combinedEl = groupEl.querySelector('[data-datetime-part="combined"]');
+      var dateEl = groupEl.querySelector('[data-datetime-part="date"]');
+
+      if (combinedEl) {
+        combinedEl.value = "";
+        combinedEl.setAttribute("value", "");
+      }
+
+      if (dateEl) {
+        dateEl.value = "";
+        dateEl.setAttribute("value", "");
+      }
+
+      clearDatetimeTimeParts(groupEl);
+      syncDatetimeTimeDisabledState(groupEl);
+      syncBlankMinuteOptionState(groupEl);
+    });
+  }
+
   function setCheckboxGroupState(formEl, groupName, checked) {
     if (!groupName) return;
 
@@ -216,4 +286,3 @@
 
   document.addEventListener("turbo:load", initializeFromDocument);
 })();
-

data/app/helpers/yummy_guide/administrate/filter_controls_helper.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module YummyGuide
+  module Administrate
+    module FilterControlsHelper
+      def admin_filter_controls(
+        dashboard: nil,
+        page: nil,
+        path: nil,
+        clear_path: nil,
+        search_options: {},
+        form: :search_options,
+        method: :get,
+        hidden_fields: {},
+        root_hidden_fields: {},
+        filter_locals: {},
+        extra_actions: [],
+        button_label: "Filter",
+        title: "Filter Options",
+        submit_label: "Filter"
+      )
+        dashboard ||= admin_filter_dashboard_from_page(page)
+        scope = form.to_s
+        current_values = admin_filter_current_values(search_options)
+        base_locals = filter_locals.merge(
+          dashboard: dashboard,
+          page: page,
+          search_options: search_options,
+          current_values: current_values,
+          form_scope: scope
+        )
+        fields = admin_filter_visible_fields(dashboard, base_locals)
+        return if fields.blank?
+
+        path ||= admin_filter_dashboard_setting(dashboard, :filter_path, :FILTER_PATH, base_locals)
+        raise ArgumentError, "admin_filter_controls requires path or dashboard FILTER_PATH" if path.blank?
+
+        clear_path ||= admin_filter_dashboard_setting(dashboard, :filter_clear_path, :FILTER_CLEAR_PATH, base_locals) || path
+        locals = filter_locals.merge(
+          dashboard: dashboard,
+          page: page,
+          path: path,
+          clear_path: clear_path,
+          search_options: search_options,
+          current_values: current_values,
+          form_scope: scope
+        )
+
+        safe_join([
+          content_tag(:div, "", class: "modal_overlay"),
+          content_tag(:div, id: "reserv-filter-options") do
+            safe_join([
+              link_to(button_label, "javascript:void(0)", class: "button"),
+              admin_filter_form(
+                fields: fields,
+                scope: scope,
+                path: path,
+                clear_path: clear_path,
+                method: method,
+                current_values: current_values,
+                hidden_fields: hidden_fields,
+                root_hidden_fields: root_hidden_fields,
+                locals: locals,
+                extra_actions: extra_actions,
+                title: title,
+                submit_label: submit_label
+              )
+            ])
+          end
+        ])
+      end
+
+      def admin_filter_dashboard_from_page(page)
+        return page.dashboard if page.respond_to?(:dashboard)
+        return unless page.respond_to?(:instance_variable_defined?) && page.instance_variable_defined?(:@dashboard)
+
+        page.instance_variable_get(:@dashboard)
+      end
+
+      def admin_filter_dashboard_setting(dashboard, method_name, constant_name, locals)
+        return if dashboard.blank?
+
+        value =
+          if dashboard.respond_to?(method_name)
+            dashboard.public_send(method_name)
+          else
+            admin_filter_dashboard_constant(dashboard, constant_name)
+          end
+
+        admin_filter_evaluate_value(value, locals)
+      end
+
+      def admin_filter_dashboard_constant(dashboard, constant_name)
+        target = dashboard.is_a?(Class) ? dashboard : dashboard.class
+        target.const_get(constant_name, false) if target.const_defined?(constant_name, false)
+      end
+
+      def admin_filter_visible_fields(dashboard, locals)
+        return [] if dashboard.blank?
+
+        YummyGuide::Administrate::Filters::Resolver
+          .attributes_for(dashboard)
+          .values
+          .select { |field| field.visible?(self, locals) }
+      end
+
+      def admin_filter_form(fields:, scope:, path:, clear_path:, method:, current_values:, hidden_fields:, root_hidden_fields:, locals:, extra_actions:, title:, submit_label:)
+        form_with(
+          url: path,
+          scope: scope,
+          method: method,
+          html: {
+            class: "filter-form",
+            data: {
+              yummy_guide_administrate_filter_form: true,
+              admin_filter_form: true
+            }
+          }
+        ) do |f|
+          safe_join([
+            admin_filter_hidden_fields(scope, hidden_fields, root_hidden_fields),
+            content_tag(:h2, title, class: "filter-form__title"),
+            content_tag(:div, class: "filter-form__body") do
+              content_tag(:table, class: "filter_table") do
+                safe_join(fields.map { |field| field.row(self, f, scope, current_values, locals) })
+              end
+            end,
+            content_tag(:div, class: "filter-form__actions") do
+              safe_join([
+                link_to("Clear", clear_path, class: "button button--outline-primary"),
+                Array(extra_actions),
+                f.submit(submit_label, class: "submit_filter")
+              ].flatten)
+            end
+          ])
+        end
+      end
+
+      def admin_filter_hidden_fields(scope, hidden_fields, root_hidden_fields)
+        root_tags = admin_filter_evaluated_hash(root_hidden_fields).map do |key, value|
+          hidden_field_tag(key, value)
+        end
+
+        scoped_tags = admin_filter_evaluated_hash(hidden_fields).map do |key, value|
+          hidden_field_tag("#{scope}[#{key}]", value)
+        end
+
+        safe_join(root_tags + scoped_tags)
+      end
+
+      def admin_filter_evaluated_hash(values)
+        values = admin_filter_evaluate_value(values, {})
+        (values || {}).to_h
+      end
+
+      def admin_filter_evaluate_value(value, locals)
+        return value unless value.respond_to?(:call)
+
+        case value.arity
+        when 0
+          value.call
+        when 1
+          value.call(self)
+        else
+          value.call(self, locals)
+        end
+      end
+
+      def admin_filter_current_values(raw_values)
+        values =
+          if raw_values.respond_to?(:to_unsafe_h)
+            raw_values.to_unsafe_h
+          elsif raw_values.respond_to?(:to_h)
+            raw_values.to_h
+          else
+            raw_values || {}
+          end
+
+        values.deep_stringify_keys
+      end
+    end
+  end
+end

data/lib/yummy_guide/administrate/engine.rb

@@ -11,17 +11,20 @@ module YummyGuide
           yummy_guide_administrate/clipboards.js
           yummy_guide_administrate/datetime_input.js
           yummy_guide_administrate/fixed_submit_actions.js
+          yummy_guide_administrate/filter_controls.js
           yummy_guide_administrate/filter_form.js
           yummy_guide_administrate/sticky_left_columns.js
           yummy_guide_administrate/sticky_table_headers.js
         ]
       end
 
-      initializer "yummy_guide.administrate.number_input_helper" do |app|
+      initializer "yummy_guide.administrate.helpers" do |app|
         app.config.to_prepare do
           next unless defined?(::Administrate::ApplicationController)
 
           ::Administrate::ApplicationController.helper YummyGuide::Administrate::NumberInputHelper
+          ::Administrate::ApplicationController.helper YummyGuide::Administrate::FilterFormHelper
+          ::Administrate::ApplicationController.helper YummyGuide::Administrate::FilterControlsHelper
         end
       end
     end

data/lib/yummy_guide/administrate/filters.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+module YummyGuide
+  module Administrate
+    module Filters
+      class Base
+        attr_reader :name, :options
+
+        def self.with_options(options = {})
+          new(options)
+        end
+
+        def initialize(options = {})
+          @options = options.symbolize_keys
+        end
+
+        def with_name(name)
+          copy = dup
+          copy.instance_variable_set(:@name, name.to_sym)
+          copy
+        end
+
+        def visible?(view_context, locals)
+          condition = options.fetch(:if, true)
+          evaluate_option(condition, view_context, locals) != false
+        end
+
+        def row(view_context, form, scope, current_values, locals)
+          view_context.content_tag(:tr) do
+            view_context.safe_join([
+              label_cell(view_context, form, locals),
+              input_cell(view_context, form, scope, current_values, locals),
+              clear_cell(view_context)
+            ])
+          end
+        end
+
+        def label_text(view_context, locals)
+          evaluated_label = evaluate_option(options[:label], view_context, locals)
+          return evaluated_label if evaluated_label.present?
+
+          name.to_s.humanize
+        end
+
+        protected
+
+        def label_cell(view_context, form, locals)
+          view_context.content_tag(:td, form.label(name, label_text(view_context, locals)))
+        end
+
+        def input_cell(view_context, form, _scope, current_values, locals)
+          view_context.content_tag(:td, input(view_context, form, current_values, locals))
+        end
+
+        def clear_cell(view_context)
+          return view_context.filter_field_clear_cell if view_context.respond_to?(:filter_field_clear_cell)
+
+          view_context.content_tag(:td, "", class: "filter-table__clear")
+        end
+
+        def current_value(current_values)
+          value = current_values[name.to_s]
+          value.presence || options[:default]
+        end
+
+        def html_options(view_context, locals)
+          options.slice(:placeholder, :inputmode, :pattern, :class, :id, :autocomplete).transform_values do |value|
+            evaluate_option(value, view_context, locals)
+          end.compact
+        end
+
+        def evaluate_option(value, view_context, locals)
+          return value unless value.respond_to?(:call)
+
+          case value.arity
+          when 0
+            value.call
+          when 1
+            value.call(view_context)
+          else
+            value.call(view_context, locals)
+          end
+        end
+
+        def normalize_options(view_context, locals)
+          raw_options = evaluate_option(options[:collection] || options[:options], view_context, locals)
+
+          Array(raw_options).map do |option|
+            if option.is_a?(Array)
+              option
+            else
+              [option, option]
+            end
+          end
+        end
+
+        def input(_view_context, _form, _current_values, _locals)
+          raise NotImplementedError
+        end
+      end
+
+      class Text < Base
+        private
+
+        def input(view_context, form, current_values, locals)
+          form.text_field(name, html_options(view_context, locals).merge(value: current_value(current_values)))
+        end
+      end
+
+      class Select < Base
+        private
+
+        def input(view_context, form, current_values, locals)
+          selected = current_value(current_values)
+          form.select(
+            name,
+            view_context.options_for_select(normalize_options(view_context, locals), selected),
+            evaluate_option(options[:select_options] || {}, view_context, locals),
+            html_options(view_context, locals)
+          )
+        end
+      end
+
+      class Checkbox < Base
+        private
+
+        def input(view_context, form, current_values, locals)
+          checked_value = options.fetch(:checked_value, "true")
+          unchecked_value = options.fetch(:unchecked_value, "false")
+          checked = ActiveModel::Type::Boolean.new.cast(current_value(current_values))
+          form.check_box(name, html_options(view_context, locals).merge(checked: checked), checked_value, unchecked_value)
+        end
+      end
+
+      class RadioGroup < Base
+        protected
+
+        def input_cell(view_context, _form, scope, current_values, locals)
+          selected = current_value(current_values).to_s
+          controls = normalize_options(view_context, locals).map do |label, value|
+            value_string = value.to_s
+            id = "#{scope}_#{name}_#{value_string.parameterize(separator: "_")}"
+            view_context.content_tag(:label, style: "display: flex; align-items: center; gap: 6px;") do
+              view_context.safe_join([
+                view_context.radio_button_tag("#{scope}[#{name}]", value, selected == value_string, id: id),
+                view_context.content_tag(:span, label)
+              ])
+            end
+          end
+
+          view_context.content_tag(:td, view_context.safe_join(controls))
+        end
+      end
+
+      class CheckboxGroup < Base
+        protected
+
+        def input_cell(view_context, _form, scope, current_values, locals)
+          selected_values = Array(current_values[name.to_s]).map(&:to_s).reject(&:blank?)
+          group_name = (options[:group] || name).to_s.dasherize
+          controls = normalize_options(view_context, locals).map do |label, value|
+            value_string = value.to_s
+            id = "#{scope}_#{name}_#{value_string.parameterize(separator: "_")}"
+            view_context.content_tag(:label, style: "display: flex; align-items: center; gap: 6px;") do
+              view_context.safe_join([
+                view_context.check_box_tag(
+                  "#{scope}[#{name}][]",
+                  value,
+                  selected_values.include?(value_string),
+                  id: id,
+                  data: { checkbox_group_item: group_name }
+                ),
+                view_context.content_tag(:span, label)
+              ])
+            end
+          end
+
+          view_context.content_tag(:td) do
+            view_context.content_tag(:div, data: { checkbox_group: group_name }) do
+              view_context.content_tag(:div, view_context.safe_join(controls), class: "filter-checkbox-group__options")
+            end
+          end
+        end
+
+        def clear_cell(view_context)
+          group_name = (options[:group] || name).to_s.dasherize
+          return view_context.checkbox_group_action_cell(target: group_name) if view_context.respond_to?(:checkbox_group_action_cell)
+
+          super
+        end
+      end
+
+      class DatetimeRange < Base
+        def row(view_context, form, scope, current_values, locals)
+          view_context.content_tag(:tr) do
+            view_context.safe_join([
+              label_cell(view_context, form, locals),
+              view_context.content_tag(:td, range_inputs(view_context, scope, current_values, locals)),
+              clear_cell(view_context)
+            ])
+          end
+        end
+
+        private
+
+        def range_inputs(view_context, scope, current_values, locals)
+          from_name = (options[:from] || :"start_#{name}").to_sym
+          to_name = (options[:to] || :"end_#{name}").to_sym
+          css_class = evaluate_option(options[:css_class] || "#{scope}_#{name}", view_context, locals)
+
+          view_context.safe_join([
+            view_context.render(
+              "yummy_guide/administrate/filter_forms/datetime_field",
+              form_scope: scope,
+              field_name: from_name,
+              current_value: current_values[from_name.to_s],
+              css_class: css_class,
+              end_target: to_name
+            ),
+            view_context.content_tag(:p, "〜", class: "filter-datetime-range-separator"),
+            view_context.render(
+              "yummy_guide/administrate/filter_forms/datetime_field",
+              form_scope: scope,
+              field_name: to_name,
+              current_value: current_values[to_name.to_s],
+              css_class: css_class,
+              end_of_day: true
+            )
+          ])
+        end
+      end
+
+      class DateRange < Base
+        def row(view_context, form, _scope, current_values, locals)
+          from_name = (options[:from] || :"start_#{name}").to_sym
+          to_name = (options[:to] || :"end_#{name}").to_sym
+
+          view_context.content_tag(:tr) do
+            view_context.safe_join([
+              label_cell(view_context, form, locals),
+              view_context.content_tag(:td) do
+                view_context.safe_join([
+                  form.date_field(from_name, value: current_values[from_name.to_s].presence || evaluate_option(options[:from_default], view_context, locals)),
+                  view_context.content_tag(:span, "〜"),
+                  form.date_field(to_name, value: current_values[to_name.to_s].presence || evaluate_option(options[:to_default], view_context, locals))
+                ])
+              end,
+              clear_cell(view_context)
+            ])
+          end
+        end
+      end
+
+      class DatetimeLocalRange < Base
+        def row(view_context, form, _scope, current_values, locals)
+          from_name = (options[:from] || :"start_#{name}").to_sym
+          to_name = (options[:to] || :"end_#{name}").to_sym
+
+          view_context.content_tag(:tr) do
+            view_context.safe_join([
+              label_cell(view_context, form, locals),
+              view_context.content_tag(:td) do
+                view_context.safe_join([
+                  form.datetime_local_field(from_name, value: current_values[from_name.to_s].presence || evaluate_option(options[:from_default], view_context, locals)),
+                  view_context.content_tag(:p, "〜", style: "text-align: center; margin: 0;"),
+                  form.datetime_local_field(to_name, value: current_values[to_name.to_s].presence || evaluate_option(options[:to_default], view_context, locals))
+                ])
+              end,
+              clear_cell(view_context)
+            ])
+          end
+        end
+      end
+
+      class Custom < Base
+        def row(view_context, form, scope, current_values, locals)
+          view_context.render(
+            options.fetch(:partial),
+            form: form,
+            form_scope: scope,
+            field: self,
+            current_values: current_values,
+            filter_locals: locals
+          )
+        end
+      end
+
+      module Resolver
+        module_function
+
+        def attributes_for(dashboard)
+          source = dashboard.respond_to?(:filter_attributes) ? dashboard.filter_attributes : constant_value(dashboard, :FILTER_ATTRIBUTES)
+          normalize_attributes(source || {})
+        end
+
+        def normalize_attributes(attributes)
+          attributes.to_h.map do |name, field|
+            [name.to_sym, normalize_field(name, field)]
+          end.to_h
+        end
+
+        def normalize_field(name, field)
+          if field.respond_to?(:with_name)
+            field.with_name(name)
+          elsif field.is_a?(Class) && field < Base
+            field.with_options.with_name(name)
+          else
+            raise ArgumentError, "Unsupported filter field for #{name}: #{field.inspect}"
+          end
+        end
+
+        def constant_value(dashboard, name)
+          target = dashboard.is_a?(Class) ? dashboard : dashboard.class
+          target.const_get(name, false) if target.const_defined?(name, false)
+        end
+      end
+    end
+  end
+end

data/lib/yummy_guide/administrate/version.rb

@@ -2,6 +2,6 @@
 
 module YummyGuide
   module Administrate
-    VERSION = "0.5.4"
+    VERSION = "0.6.1"
   end
 end

data/lib/yummy_guide/administrate.rb

@@ -4,7 +4,10 @@ require "rails"
 require "administrate"
 
 require_relative "../../app/helpers/yummy_guide/administrate/number_input_helper"
+require_relative "../../app/helpers/yummy_guide/administrate/filter_form_helper"
+require_relative "../../app/helpers/yummy_guide/administrate/filter_controls_helper"
 require_relative "administrate/version"
+require_relative "administrate/filters"
 require_relative "administrate/engine"
 
 module YummyGuide

data/spec/yummy_guide/administrate/filter_controls_helper_spec.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "nokogiri"
+
+RSpec.describe YummyGuide::Administrate::FilterControlsHelper do
+  subject(:helper_host) do
+    Class.new do
+      include ActionView::Context
+      include ActionView::Helpers::FormHelper
+      include ActionView::Helpers::FormOptionsHelper
+      include ActionView::Helpers::FormTagHelper
+      include ActionView::Helpers::OutputSafetyHelper
+      include ActionView::Helpers::TagHelper
+      include ActionView::Helpers::UrlHelper
+      include YummyGuide::Administrate::FilterControlsHelper
+    end.new
+  end
+
+  def fragment(html)
+    Nokogiri::HTML.fragment(html)
+  end
+
+  describe "#admin_filter_controls" do
+    # dashboard の FILTER_ATTRIBUTES から Filter ボタンとフォーム項目を描画することを確認する
+    it "renders controls from dashboard filter attributes" do
+      dashboard = Class.new
+      dashboard.const_set(
+        :FILTER_ATTRIBUTES,
+        {
+          keyword: YummyGuide::Administrate::Filters::Text.with_options(label: "Keyword"),
+          status: YummyGuide::Administrate::Filters::Select.with_options(
+            label: "Status",
+            collection: [["Open", "open"], ["Closed", "closed"]]
+          )
+        }.freeze
+      )
+
+      html = helper_host.admin_filter_controls(
+        dashboard: dashboard,
+        path: "/admin/resources",
+        search_options: { keyword: "tokyo", status: "closed" }
+      )
+      document = fragment(html)
+
+      expect(document.at_css("#reserv-filter-options > a.button").text).to eq("Filter")
+      expect(document.at_css("form.filter-form")["action"]).to eq("/admin/resources")
+      expect(document.at_css('input[name="search_options[keyword]"]')["value"]).to eq("tokyo")
+      expect(document.at_css('select[name="search_options[status]"] option[selected]')["value"]).to eq("closed")
+    end
+
+    # dashboard に定義した FILTER_PATH をフィルター送信先として利用できることを確認する
+    it "uses dashboard filter path when no explicit path is passed" do
+      dashboard = Class.new
+      dashboard.const_set(
+        :FILTER_ATTRIBUTES,
+        {
+          keyword: YummyGuide::Administrate::Filters::Text.with_options(label: "Keyword")
+        }.freeze
+      )
+      dashboard.const_set(:FILTER_PATH, ->(view, _locals) { view.filter_path })
+
+      helper_host.define_singleton_method(:filter_path) { "/admin/dashboard-filters" }
+
+      html = helper_host.admin_filter_controls(dashboard: dashboard)
+      document = fragment(html)
+
+      expect(document.at_css("form.filter-form")["action"]).to eq("/admin/dashboard-filters")
+    end
+
+    # dashboard にフィルター定義が存在しない場合は Filter ボタンを描画しないことを確認する
+    it "does not render controls when dashboard has no filter attributes" do
+      expect(helper_host.admin_filter_controls(dashboard: Class.new, path: "/admin/resources")).to be_nil
+    end
+  end
+end

data/spec/yummy_guide/administrate/filters_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe YummyGuide::Administrate::Filters do
+  describe YummyGuide::Administrate::Filters::Resolver do
+    # dashboard に定義した Field クラス型フィルターへ属性名が付与されることを確認する
+    it "normalizes dashboard filter attributes with field names" do
+      dashboard = Class.new
+      dashboard.const_set(
+        :FILTER_ATTRIBUTES,
+        {
+          keyword: YummyGuide::Administrate::Filters::Text.with_options(label: "Keyword")
+        }.freeze
+      )
+
+      fields = described_class.attributes_for(dashboard)
+
+      expect(fields[:keyword]).to be_a(YummyGuide::Administrate::Filters::Text)
+      expect(fields[:keyword].name).to eq(:keyword)
+    end
+  end
+
+  describe "#visible?" do
+    # view context に依存する条件でフィルター表示を切り替えられることを確認する
+    it "evaluates visibility conditions with the view context" do
+      view_context = double("view_context", owner?: true)
+      field = YummyGuide::Administrate::Filters::Text
+        .with_options(if: ->(view, _locals) { !view.owner? })
+        .with_name(:owner_name)
+
+      expect(field.visible?(view_context, {})).to be(false)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yummy-guide-generic-administrate
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.1
 platform: ruby
 authors:
 - akatsuki-kk
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-18 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: administrate
@@ -92,6 +92,7 @@ files:
 - app/assets/images/yummy_guide_administrate/icon-copy.svg
 - app/assets/javascripts/yummy_guide_administrate/clipboards.js
 - app/assets/javascripts/yummy_guide_administrate/datetime_input.js
+- app/assets/javascripts/yummy_guide_administrate/filter_controls.js
 - app/assets/javascripts/yummy_guide_administrate/filter_form.js
 - app/assets/javascripts/yummy_guide_administrate/fixed_submit_actions.js
 - app/assets/javascripts/yummy_guide_administrate/sticky_left_columns.js
@@ -108,6 +109,7 @@ files:
 - app/fields/yummy_guide/administrate/fields/version_whodunnit_field.rb
 - app/helpers/yummy_guide/administrate/collection_helper.rb
 - app/helpers/yummy_guide/administrate/datetime_input_helper.rb
+- app/helpers/yummy_guide/administrate/filter_controls_helper.rb
 - app/helpers/yummy_guide/administrate/filter_form_helper.rb
 - app/helpers/yummy_guide/administrate/number_input_helper.rb
 - app/views/fields/number/_form.html.erb
@@ -129,6 +131,7 @@ files:
 - lib/yummy/guide/generic/administrate.rb
 - lib/yummy_guide/administrate.rb
 - lib/yummy_guide/administrate/engine.rb
+- lib/yummy_guide/administrate/filters.rb
 - lib/yummy_guide/administrate/version.rb
 - spec/spec_helper.rb
 - spec/views/fields/number/form_spec.rb
@@ -140,7 +143,9 @@ files:
 - spec/yummy_guide/administrate/fields/json_pretty_field_spec.rb
 - spec/yummy_guide/administrate/fields/version_item_field_spec.rb
 - spec/yummy_guide/administrate/fields/version_whodunnit_field_spec.rb
+- spec/yummy_guide/administrate/filter_controls_helper_spec.rb
 - spec/yummy_guide/administrate/filter_form_helper_spec.rb
+- spec/yummy_guide/administrate/filters_spec.rb
 - spec/yummy_guide/administrate/number_input_helper_spec.rb
 - yummy-guide-generic-administrate.gemspec
 homepage: https://github.com/yummy-guide/generic-administrate