yummy-guide-generic-administrate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b78001f457aaa653797c44c84f1d169f7e870932e5b7ea43ae1d3994ecab9747
+  data.tar.gz: 437ffe942299cbda22d3eca1e72ecc625069880862848b94d3da3520cb3ecf12
+SHA512:
+  metadata.gz: 8a8b10627365f4b549f43701974d3e8ab0066d6a656bdab19fbe310dce3ed258b1b80e58db16ce72219bda72030f9269fd71a752324a016cc44426464d64d0c4
+  data.tar.gz: 589d405d80686573b6fd8efd2a45795861e010203b703f85e1a0c142dec044c8cf603189480f1adfd581c8fc24c61690a56335c1b487d3be869322c7644bdc91

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gemspec
+

data/README.md

@@ -0,0 +1,243 @@
+# yummy-guide-generic-administrate
+
+`yummy-guide-generic-administrate` は、Yummy Guide 系 Rails アプリで共通利用する
+[`Administrate`](https://github.com/thoughtbot/administrate) 拡張をまとめた Rails
+Engine です。
+
+`Administrate` 本体を置き換えるものではなく、ダッシュボードの共通既定値、
+フィルター UI、一覧表示 helper、共通 field などを再利用しやすくするための補助
+gem です。
+
+## 前提
+
+- Ruby `>= 3.2.2`
+- Rails `>= 7.0`, `< 7.2`
+- Administrate `>= 0.19`, `< 0.21`
+- `sprockets-rails`
+
+## インストール
+
+`Gemfile` に追加します。
+
+```ruby
+gem "yummy-guide-generic-administrate"
+```
+
+その後、依存 gem をインストールします。
+
+```bash
+bundle install
+```
+
+## 提供するもの
+
+- `YummyGuide::Administrate::ApplicationDashboard`
+  - 一覧画面の既定ソートと固定列数の共通基底クラス
+- `YummyGuide::Administrate::DefaultSorting`
+  - dashboard 側の既定ソート設定を controller に反映する concern
+- `YummyGuide::Administrate::DatetimeFilterParameters`
+  - 日付、時、分の分割パラメータを 1 つの datetime 文字列へ正規化する concern
+- `YummyGuide::Administrate::CollectionHelper`
+  - 一覧テーブルの固定列数、リンク生成、action partial 解決を補助する helper
+- `YummyGuide::Administrate::FilterFormHelper`
+  - datetime フィルターや checkbox group の組み立てを補助する helper
+- 共通 partial / assets
+  - collection partial
+  - filter form partial
+  - `filter_form.js`
+  - `sticky_left_columns.js`
+  - `components.css`
+- 共通 field
+  - `YummyGuide::Administrate::Fields::JsonPrettyField`
+  - `YummyGuide::Administrate::Fields::VersionItemField`
+  - `YummyGuide::Administrate::Fields::VersionWhodunnitField`
+  - `YummyGuide::Administrate::Fields::Area::PictureField`
+
+## 利用方法
+
+### Dashboard の基底クラス
+
+共通の既定ソートと固定列数設定を使う場合は、dashboard を
+`YummyGuide::Administrate::ApplicationDashboard` から継承します。
+
+```ruby
+class ApplicationDashboard < YummyGuide::Administrate::ApplicationDashboard
+end
+```
+
+必要に応じて各 dashboard 側で上書きできます。
+
+```ruby
+class Admin::ArticleDashboard < ApplicationDashboard
+  COLLECTION_ATTRIBUTES = %i[id title status created_at].freeze
+  COLLECTION_SORTABLE_ATTRIBUTES = %i[id title status created_at].freeze
+  INDEX_FIXED_COLUMNS_COUNT = 2
+
+  def default_sorting_attribute
+    :published_at
+  end
+
+  def default_sorting_direction
+    :desc
+  end
+end
+```
+
+### Controller concern / helper
+
+管理画面の基底 controller で共通 concern と helper を読み込みます。
+
+```ruby
+class Admin::ApplicationController < Administrate::ApplicationController
+  include YummyGuide::Administrate::DefaultSorting
+  include YummyGuide::Administrate::DatetimeFilterParameters
+
+  helper YummyGuide::Administrate::CollectionHelper
+  helper YummyGuide::Administrate::FilterFormHelper
+end
+```
+
+### Collection partial
+
+ホストアプリ側の `app/views/administrate/application/_collection.html.erb` から、
+engine の共通 partial に委譲します。
+
+```erb
+<%= render "yummy_guide/administrate/administrate/application/collection",
+           collection_presenter: collection_presenter,
+           page: page,
+           resources: resources,
+           table_title: table_title,
+           namespace: namespace,
+           resource_class: resource_class,
+           collection_field_name: collection_field_name %>
+```
+
+### Datetime filter
+
+filter form の枠と datetime 入力 partial を組み合わせて利用できます。
+
+```erb
+<%= render "yummy_guide/administrate/filter_forms/frame",
+           path: path,
+           form: form,
+           method: method,
+           current_values: search_options do |f, values| %>
+  <tr>
+    <td><%= f.label :start_at, "開始日時" %></td>
+    <td>
+      <%= render "yummy_guide/administrate/filter_forms/datetime_field",
+                 form_scope: form,
+                 field_name: :start_at,
+                 current_value: values["start_at"],
+                 css_class: "#{form}_start_at" %>
+    </td>
+  </tr>
+<% end %>
+```
+
+controller 側では、必要な filter key を指定して datetime パラメータを正規化します。
+
+```ruby
+def search_term
+  resource_params = params[resource_name] || params[resource_name.to_sym] || {}
+  raw_filters = resource_params[:search] || resource_params["search"] || {}
+
+  normalized_filters = normalize_datetime_filter_params(
+    raw_filters,
+    keys: %i[start_at end_at]
+  )
+
+  normalized_filters
+end
+```
+
+### Asset の読み込み
+
+この engine の asset はホストアプリ側で明示的に読み込んでください。
+
+```js
+//= require yummy_guide_administrate/filter_form
+//= require yummy_guide_administrate/sticky_left_columns
+```
+
+```scss
+ *= require yummy_guide_administrate/components
+```
+
+### Custom field
+
+dashboard から共通 field を利用できます。
+
+```ruby
+ATTRIBUTE_TYPES = {
+  metadata: YummyGuide::Administrate::Fields::JsonPrettyField,
+  item: YummyGuide::Administrate::Fields::VersionItemField.with_options(namespace: :admin),
+  whodunnit: YummyGuide::Administrate::Fields::VersionWhodunnitField.with_options(
+    namespace: :admin,
+    user_class: "User"
+  ),
+  pictures: YummyGuide::Administrate::Fields::Area::PictureField
+}.freeze
+```
+
+## 各 field の用途
+
+### JsonPrettyField
+
+JSON 文字列または JSON 互換オブジェクトを、整形済みの文字列として表示します。
+
+### VersionItemField
+
+PaperTrail の `item` や `reify` 結果をもとに、対象 resource のラベルと詳細画面への
+リンクを表示します。`namespace` は `:admin` が既定です。
+
+### VersionWhodunnitField
+
+PaperTrail の `whodunnit` から操作ユーザーを解決して表示します。
+
+- 既定では `User` クラスを参照します
+- `user_class` で別クラスを指定できます
+- `user_label` に proc を渡すと表示ラベルを上書きできます
+
+### Area::PictureField
+
+画像添付用の field です。Active Storage の添付オブジェクト、または `attachments`
+を返すオブジェクトを前提としています。
+
+必要に応じて以下の option を指定できます。
+
+- `max_uploads`
+- `input_name`
+- `purge_input_name`
+- `attachment_url`
+- `preview_url`
+
+## 参照
+
+- Administrate 公式リポジトリ
+  - <https://github.com/thoughtbot/administrate>
+- Administrate gem ページ
+  - <https://rubygems.org/gems/administrate>
+
+## リリース手順
+
+このリポジトリは `bundler/gem_tasks` を利用しているため、標準の gem リリースタスク
+で公開できます。
+
+1. `lib/yummy_guide/administrate/version.rb` の `VERSION` を更新する
+2. 必要な変更を commit 済みの状態にする
+3. 必要に応じて `bundle exec rake spec` で確認する
+4. `bundle exec rake release` を実行する
+
+`bundle exec rake release` を実行すると、現在の `VERSION` をもとに `v<version>` の
+git tag を作成し、gem を build して `rubygems.org` へ push します。
+
+事前に RubyGems への push 権限があること、ローカル環境で `gem push` が利用できる
+ことを確認してください。
+
+## 注意点
+
+- asset は precompile 対象に追加されますが、ホストアプリ側での読み込み設定は別途必要です
+- `VersionWhodunnitField` は対象ユーザー class や表示ラベルをアプリ事情に合わせて調整してください
+- `Area::PictureField` の URL 解決は、必要なら option で明示的に上書きしてください

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+begin
+  require "rspec/core/rake_task"
+
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+  task default: :test
+end
+

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

@@ -0,0 +1,219 @@
+(function() {
+  var FORM_SELECTOR = "[data-yummy-guide-administrate-filter-form]";
+
+  function initializeForms(root) {
+    var forms = [];
+
+    if (root.matches && root.matches(FORM_SELECTOR)) {
+      forms.push(root);
+    }
+
+    if (root.querySelectorAll) {
+      root.querySelectorAll(FORM_SELECTOR).forEach(function(formEl) {
+        forms.push(formEl);
+      });
+    }
+
+    forms.forEach(initializeForm);
+  }
+
+  function initializeForm(formEl) {
+    if (formEl.dataset.ygAdministrateFilterFormInitialized === "true") {
+      syncDatetimeFilterFields(formEl);
+      return;
+    }
+
+    formEl.dataset.ygAdministrateFilterFormInitialized = "true";
+    formEl.addEventListener("submit", function() {
+      syncDatetimeFilterFields(formEl);
+    });
+
+    formEl.querySelectorAll("[data-datetime-filter]").forEach(function(groupEl) {
+      groupEl.addEventListener("change", function(event) {
+        handleDatetimeFilterChange(formEl, groupEl, event);
+      });
+
+      syncBlankMinuteOptionState(groupEl);
+      syncDatetimeTimeDisabledState(groupEl);
+    });
+
+    formEl.querySelectorAll('[data-behavior="filter-form-clear"]').forEach(function(buttonEl) {
+      buttonEl.addEventListener("click", function() {
+        clearFormFields(formEl);
+      });
+    });
+
+    formEl.querySelectorAll('[data-behavior="checkbox-group-select-all"]').forEach(function(buttonEl) {
+      buttonEl.addEventListener("click", function() {
+        setCheckboxGroupState(formEl, buttonEl.dataset.target, true);
+      });
+    });
+
+    formEl.querySelectorAll('[data-behavior="checkbox-group-clear-all"]').forEach(function(buttonEl) {
+      buttonEl.addEventListener("click", function() {
+        setCheckboxGroupState(formEl, buttonEl.dataset.target, false);
+      });
+    });
+
+    syncDatetimeFilterFields(formEl);
+  }
+
+  function clearFormFields(formEl) {
+    formEl.querySelectorAll("input, select, textarea").forEach(function(fieldEl) {
+      if (fieldEl.disabled || fieldEl.type === "hidden" || fieldEl.type === "submit") {
+        return;
+      }
+
+      if (fieldEl.tagName === "SELECT") {
+        fieldEl.value = "";
+        return;
+      }
+
+      if (fieldEl.type === "checkbox" || fieldEl.type === "radio") {
+        fieldEl.checked = false;
+        return;
+      }
+
+      fieldEl.value = "";
+    });
+
+    formEl.querySelectorAll("[data-datetime-filter]").forEach(function(groupEl) {
+      clearDatetimeTimeParts(groupEl);
+      syncDatetimeTimeDisabledState(groupEl);
+      syncBlankMinuteOptionState(groupEl);
+    });
+
+    syncDatetimeFilterFields(formEl);
+  }
+
+  function setCheckboxGroupState(formEl, groupName, checked) {
+    if (!groupName) return;
+
+    formEl.querySelectorAll('[data-checkbox-group-item="' + groupName + '"]').forEach(function(checkboxEl) {
+      if (!checkboxEl.disabled) {
+        checkboxEl.checked = checked;
+      }
+    });
+  }
+
+  function handleDatetimeFilterChange(formEl, groupEl, event) {
+    if (event.target && event.target.dataset.datetimePart === "date") {
+      if (event.target.value) {
+        syncRangeEndDate(formEl, groupEl);
+      } else {
+        clearDatetimeTimeParts(groupEl);
+      }
+    }
+
+    if (event.target && event.target.dataset.datetimePart === "hour") {
+      syncDatetimeMinuteOnHourChange(groupEl);
+    }
+
+    if (event.target && event.target.dataset.datetimePart === "minute") {
+      preventBlankDatetimeMinute(groupEl);
+    }
+
+    syncDatetimeTimeDisabledState(groupEl);
+    syncBlankMinuteOptionState(groupEl);
+    syncDatetimeFilterFields(formEl);
+  }
+
+  function syncRangeEndDate(formEl, groupEl) {
+    var endTarget = groupEl.dataset.datetimeEndTarget;
+    if (!endTarget) return;
+
+    var startDateEl = groupEl.querySelector('[data-datetime-part="date"]');
+    if (!startDateEl || !startDateEl.value) return;
+
+    var endGroupEl = formEl.querySelector('[data-datetime-field="' + endTarget + '"]');
+    if (!endGroupEl) return;
+
+    var endDateEl = endGroupEl.querySelector('[data-datetime-part="date"]');
+    if (!endDateEl || endDateEl.value) return;
+
+    endDateEl.value = startDateEl.value;
+  }
+
+  function clearDatetimeTimeParts(groupEl) {
+    var hourEl = groupEl.querySelector('[data-datetime-part="hour"]');
+    var minuteEl = groupEl.querySelector('[data-datetime-part="minute"]');
+
+    if (hourEl) hourEl.value = "";
+    if (minuteEl) minuteEl.value = "";
+  }
+
+  function syncDatetimeMinuteOnHourChange(groupEl) {
+    var hourEl = groupEl.querySelector('[data-datetime-part="hour"]');
+    var minuteEl = groupEl.querySelector('[data-datetime-part="minute"]');
+    if (!hourEl || !minuteEl) return;
+
+    minuteEl.value = hourEl.value ? "00" : "";
+  }
+
+  function preventBlankDatetimeMinute(groupEl) {
+    var hourEl = groupEl.querySelector('[data-datetime-part="hour"]');
+    var minuteEl = groupEl.querySelector('[data-datetime-part="minute"]');
+    if (!hourEl || !minuteEl) return;
+
+    if (hourEl.value && minuteEl.value === "") {
+      minuteEl.value = "00";
+    }
+  }
+
+  function syncBlankMinuteOptionState(groupEl) {
+    var hourEl = groupEl.querySelector('[data-datetime-part="hour"]');
+    var minuteEl = groupEl.querySelector('[data-datetime-part="minute"]');
+    if (!hourEl || !minuteEl) return;
+
+    var blankOptionEl = minuteEl.querySelector('option[value=""]');
+    if (blankOptionEl) {
+      blankOptionEl.disabled = !!hourEl.value;
+    }
+  }
+
+  function syncDatetimeTimeDisabledState(groupEl) {
+    var dateEl = groupEl.querySelector('[data-datetime-part="date"]');
+    var hourEl = groupEl.querySelector('[data-datetime-part="hour"]');
+    var minuteEl = groupEl.querySelector('[data-datetime-part="minute"]');
+    var dateDisabled = !dateEl || !dateEl.value;
+    var minuteDisabled = dateDisabled || !hourEl || !hourEl.value;
+
+    if (hourEl) hourEl.disabled = dateDisabled;
+    if (minuteEl) minuteEl.disabled = minuteDisabled;
+  }
+
+  function syncDatetimeFilterFields(formEl) {
+    formEl.querySelectorAll("[data-datetime-filter]").forEach(function(groupEl) {
+      var combinedEl = groupEl.querySelector('[data-datetime-part="combined"]');
+      var dateEl = groupEl.querySelector('[data-datetime-part="date"]');
+      var hourEl = groupEl.querySelector('[data-datetime-part="hour"]');
+      var minuteEl = groupEl.querySelector('[data-datetime-part="minute"]');
+
+      if (!combinedEl || !dateEl || !hourEl || !minuteEl) return;
+
+      syncDatetimeTimeDisabledState(groupEl);
+
+      if (!dateEl.value) {
+        combinedEl.value = "";
+        combinedEl.setAttribute("value", "");
+        return;
+      }
+
+      combinedEl.value = hourEl.value && minuteEl.value ? dateEl.value + "T" + hourEl.value + ":" + minuteEl.value : dateEl.value;
+      combinedEl.setAttribute("value", combinedEl.value);
+    });
+  }
+
+  function initializeFromDocument() {
+    initializeForms(document);
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initializeFromDocument, { once: true });
+  } else {
+    initializeFromDocument();
+  }
+
+  document.addEventListener("turbo:load", initializeFromDocument);
+})();
+

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

@@ -0,0 +1,141 @@
+(function() {
+  var TABLE_SELECTOR = "table[data-fixed-columns-count]";
+  var resizeObservers = new WeakMap();
+
+  function directCells(row) {
+    return Array.from(row.children).filter(function(cell) {
+      return cell.tagName === "TH" || cell.tagName === "TD";
+    });
+  }
+
+  function preciseNumber(value) {
+    return Math.round(value * 1000) / 1000;
+  }
+
+  function measuredWidth(element) {
+    if (!element) return 0;
+
+    var rectWidth = element.getBoundingClientRect().width;
+    return preciseNumber(rectWidth || element.offsetWidth || 0);
+  }
+
+  function cssPixelValue(value) {
+    return preciseNumber(value) + "px";
+  }
+
+  function resetStickyColumns(table) {
+    table.querySelectorAll(".sticky-left").forEach(function(cell) {
+      cell.classList.remove("sticky-left", "sticky-left--last");
+      cell.style.removeProperty("left");
+    });
+  }
+
+  function fixedColumnsCount(table) {
+    var parsedCount = parseInt(table.dataset.fixedColumnsCount || "0", 10);
+    return Number.isNaN(parsedCount) ? 0 : Math.max(parsedCount, 0);
+  }
+
+  function stickyOffsets(table, count) {
+    var headerRow = table.querySelector("thead tr");
+    if (!headerRow) return [];
+
+    var widths = directCells(headerRow).slice(0, count).map(function(cell) {
+      return measuredWidth(cell);
+    });
+
+    if (!widths.some(Boolean)) {
+      Array.from(table.querySelectorAll("tbody tr, tfoot tr")).some(function(row) {
+        var cells = directCells(row);
+        if (cells.length < count || cells.some(function(cell) { return cell.colSpan > 1; })) return false;
+
+        widths = cells.slice(0, count).map(function(cell) {
+          return measuredWidth(cell);
+        });
+        return widths.some(Boolean);
+      });
+    }
+
+    var offsets = [];
+    var currentLeft = 0;
+
+    widths.forEach(function(width) {
+      offsets.push(currentLeft);
+      currentLeft += width;
+    });
+
+    return offsets;
+  }
+
+  function applyStickyColumns(table) {
+    resetStickyColumns(table);
+
+    var count = fixedColumnsCount(table);
+    if (count === 0) return;
+
+    var offsets = stickyOffsets(table, count);
+    if (offsets.length === 0) return;
+
+    table.querySelectorAll("thead tr, tbody tr, tfoot tr").forEach(function(row) {
+      var cells = directCells(row);
+      if (cells.length === 0 || cells.some(function(cell) { return cell.colSpan > 1; })) return;
+
+      cells.slice(0, offsets.length).forEach(function(cell, index) {
+        cell.classList.add("sticky-left");
+        if (index === offsets.length - 1) {
+          cell.classList.add("sticky-left--last");
+        }
+        cell.style.left = cssPixelValue(offsets[index]);
+      });
+    });
+  }
+
+  function observeStickyColumns(table) {
+    if (!window.ResizeObserver || resizeObservers.has(table)) return;
+
+    var observer = new ResizeObserver(function() {
+      window.requestAnimationFrame(function() {
+        applyStickyColumns(table);
+      });
+    });
+
+    observer.observe(table);
+    if (table.parentElement) {
+      observer.observe(table.parentElement);
+    }
+
+    resizeObservers.set(table, observer);
+  }
+
+  function initializeStickyColumns(root) {
+    var tables = [];
+
+    if (root.matches && root.matches(TABLE_SELECTOR)) {
+      tables.push(root);
+    }
+
+    if (root.querySelectorAll) {
+      root.querySelectorAll(TABLE_SELECTOR).forEach(function(table) {
+        tables.push(table);
+      });
+    }
+
+    tables.forEach(function(table) {
+      applyStickyColumns(table);
+      observeStickyColumns(table);
+    });
+  }
+
+  function initializeFromDocument() {
+    initializeStickyColumns(document);
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initializeFromDocument, { once: true });
+  } else {
+    initializeFromDocument();
+  }
+
+  document.addEventListener("turbo:load", initializeFromDocument);
+  window.addEventListener("resize", initializeFromDocument);
+})();
+