activeadmin_favorites 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 51027c5b7293ba07e01be5677e4785b9d682c177ef6cea6137b4f658cb2ede71
+  data.tar.gz: 24bbfd1df143374ccd612f14e6bec75967a44571ad58013d1203ca03c44c02be
+SHA512:
+  metadata.gz: e62dc3e8a67dcf78d388d00764eef5f9e4051d7ae446680d5c28775eebd6b3efb5c09443b19a0cf64e2333bdb4acfe03fbae62cc6021ec4b84d19287b1cb11ea
+  data.tar.gz: 51fad41e3d2841c6d4d55758e33e62e74539c96dc27035dcac0ddf5de2568a197da9b921aee3f90467e2233ca4554adc23659765acb166a9d3696130c11a1785

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# CHANGELOG
+
+## Unreleased
+
+- CI: run Rails 7.2 appraisal on Ruby 3.4; refresh lockfiles for current advisories (`loofah` 2.25.2, `rails-html-sanitizer` 1.7.1) and development gems (`rbs` ~> 4).
+
+## 0.1.0 (2026-07-13)
+
+- Initial public release: saved filter favorites and view lens personalization for ActiveAdmin 4.
+- STI storage on configurable `admin_favorites` (`FiltersFavorite`, `LensFavorite`, `CombinedFavorite`).
+- ActiveAdmin resource at `/admin/favorites`.
+- Request-scoped `ViewLens::Applicator` state via `ActiveSupport::CurrentAttributes`.
+- Deferred catalog JSON for cogwheel column and panel toggles after table render.
+- Configurable user association via `UserRecord` (`user_id` defaults).
+- Engine migration append with host-version deduplication.
+- `rails activeadmin_favorites:install` generator and `activeadmin_favorites:install:migrations` rake task.
+- English locale; host locale template for copy into additional languages.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone. We operate on principles of mutual respect, privacy, and authentic engagement. We value substantive contributions and clarity on intentions.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Authenticity: engaging with genuine curiosity and admitting uncertainty rather than feigning knowledge.
+- Responsible innovation: taking full responsibility for any content or code contributed, whether manually written or generated by automation tools.
+- Gentle correction: responding politely to errors. We view mistakes as opportunities for learning, provided they are addressed with humility.
+- Inclusive language: using language that welcomes diverse perspectives and respects the privacy and identity of all participants.
+
+Examples of unacceptable behavior include:
+
+- Harassment: public or private harassment, trolling, or insulting comments.
+- Weaponized complexity: using jargon or overwhelming volume (including automated spam) to silence others.
+- Publishing private information: sharing others' data or personal context without explicit permission.
+
+## Artificial intelligence and automation
+
+In accordance with our commitment to collective awareness:
+
+- Contributors are responsible for the accuracy and security of any AI-generated artifacts they submit.
+- "The AI wrote it" is not a valid excuse for introducing bugs, security vulnerabilities, or bias.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at contact@kiskolabs.com. All complaints will be reviewed and investigated promptly and fairly.

data/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing Guidelines
+
+Thank you for your interest in contributing to activeadmin_favorites. We value learning over perfection but require rigor and responsibility.
+
+## The golden rule of automation
+
+We welcome the use of AI and automation tools to reduce toil, but you must strictly adhere to the following:
+
+1. You are the author. You act as the responsible agent for any code you submit. You must review, debug, and understand every line.
+2. Manage cognitive load. Do not submit massive, unreviewed automated dumps. Respect the reviewers' time by annotating complex logic.
+3. Security. Never feed project secrets or private context into public AI models.
+
+## How to contribute
+
+### Reporting issues
+
+- Verify accuracy before posting. Avoid generalizations.
+- Use issue templates to provide clear goals, constraints, and reproduction steps.
+
+### Pull request process
+
+- Scope: keep PRs focused on a single goal.
+- Context: explain why the change is necessary.
+- Testing: run `make test` locally before opening a PR.
+
+### Review process
+
+- We encourage productive friction. Expect questions about your approach.
+- If a reviewer suggests a change, view it as mutual aid, not criticism.

data/GOVERNANCE.md

@@ -0,0 +1,29 @@
+# Project Governance
+
+## Overview
+
+This project balances individual autonomy with collective coordination. We aim for a workflow that supports rapid iteration while maintaining strict guardrails for safety and architectural integrity.
+
+## Roles
+
+### Contributors
+
+Anyone who submits code, documentation, or participates in discussions. Contributors are expected to exercise direct action—taking ownership of problems they identify—while adhering to our quality standards.
+
+### Maintainers (Human Oversight)
+
+Maintainers are responsible for:
+
+1. Strategic judgment: defining scope and architectural direction.
+2. Review: verifying that contributions (human or automated) meet security and logic standards.
+3. Consensus building: facilitating decisions when the community is divided.
+
+## Decision making process
+
+### Lazy consensus
+
+For most routine changes, we operate on lazy consensus. If a proposal is made and no objections are raised within two weeks, it is considered approved.
+
+### Strategic alignment
+
+Major architectural changes, high-risk automation integrations, or changes that affect business logic require explicit approval from the maintainers. We prioritize substance over performance—a change must solve a real problem, not just appear polished.

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amkisko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# activeadmin_favorites
+
+[![Gem Version](https://badge.fury.io/rb/activeadmin_favorites.svg)](https://badge.fury.io/rb/activeadmin_favorites) [![Test Status](https://github.com/amkisko/activeadmin_favorites.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/activeadmin_favorites.rb/actions/workflows/test.yml)
+
+Saved filter favorites, per-resource view lens defaults, and a cogwheel personalization UI for ActiveAdmin 4 index and show pages.
+
+## Requirements
+
+- Ruby 3.2+ (CI matrix: Ruby 3.4, 4.0, and TruffleRuby)
+- Rails 7.2+ (Rails 7.2 and 8.1 tested in CI)
+- ActiveAdmin 4.0.0.beta13+
+- PostgreSQL for production migrations (`jsonb` columns and concurrent index helpers)
+
+## Install
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "activeadmin_favorites"
+```
+
+Run the install generator:
+
+```bash
+bin/rails generate activeadmin_favorites:install
+bin/rails db:migrate
+```
+
+Or copy migrations manually:
+
+```bash
+bin/rails activeadmin_favorites:install:migrations
+bin/rails db:migrate
+```
+
+Greenfield apps pick up engine migrations automatically when no matching version exists in `db/migrate/`.
+
+Configure the host app (the generator writes `config/initializers/activeadmin_favorites.rb` with neutral defaults):
+
+```ruby
+ActiveAdmin::Favorites.configure do |config|
+  config.user_class = "User"
+  config.user_foreign_key = :user_id
+  config.user_association_name = :user
+  config.user_label_method = :email
+  config.current_user_method = :current_user
+end
+```
+
+Add `ActiveAdmin::Favorites::FavoritePolicy` in the host app (the generator copies a template). Point `has_many :favorites` on your user model at `ActiveAdmin::Favorites::Favorite`.
+
+Configure the table name when needed:
+
+```ruby
+ActiveAdmin::Favorites.configure do |config|
+  config.table_name = "admin_favorites"
+end
+```
+
+When using ActionPolicy, add `save_lens_favorite?` and `reset?` to `ActiveAdmin::PagePolicy` (or equivalent) so the view lens preference page actions authorize correctly.
+
+### Locales
+
+English ships with the gem. Copy `config/locales/activeadmin_favorites.host.yml.example` into your locale files and translate `active_admin.favorites` keys.
+
+## Favorite kinds
+
+| Kind | Stores |
+|------|--------|
+| `filters` | scope, sort, ransack query, macros |
+| `lens` | hidden columns, filters, panels, rows, action items |
+| `combined` | filters and layout together |
+
+## View lens layout schema
+
+```json
+{
+  "version": 1,
+  "hidden": {
+    "columns": ["created_at"],
+    "filters": ["status"],
+    "action_items": ["new"],
+    "panels": ["details"],
+    "show_rows": ["author"]
+  }
+}
+```
+
+Version 1 supports show/hide only. Column reorder is deferred.
+
+Catalog entries are discovered at render time from ActiveAdmin columns, filters, panels, and show rows. Use `lens_id:` on custom columns or panels when auto ids are unstable. Block columns without a title receive stable `block_column_N` ids automatically. Personalization catalog data is injected on every index layout, not only table indexes.
+
+## Personalization UI
+
+The gem installs:
+
+- **Add to favorites** on index pages (saved filters)
+- **Personalize page** cogwheel on index and show pages
+- **Favorites** hub with type tabs (all, filters, lens, combined)
+
+Defaults are stored in `active_admin_view_lens_defaults`. Named lens favorites and combined favorites use `admin_favorites.layout`.
+
+## Development
+
+```bash
+bundle install
+bundle exec appraisal install
+make lint
+make test
+```
+
+See `spec/README.md` for focused runs and coverage notes.
+
+If native extensions fail to load after switching Ruby installs (for example mise vs rbenv with the same version), wipe and reinstall both bundle trees with one active Ruby:
+
+```bash
+rm -rf vendor/bundle
+bundle install
+
+rm -rf gemfiles/vendor/bundle
+bundle exec appraisal install
+```
+
+## Links
+
+- [GitHub](https://github.com/amkisko/activeadmin_favorites.rb)
+- [GitLab](https://gitlab.com/amkisko/activeadmin_favorites.rb)
+- [RubyGems](https://rubygems.org/gems/activeadmin_favorites)
+- [libraries.io](https://libraries.io/rubygems/activeadmin_favorites)
+- [Deps.dev](https://deps.dev/rubygems/activeadmin_favorites)
+- [SonarCloud](https://sonarcloud.io/project/overview?id=amkisko_activeadmin_favorites.rb)
+- [Snyk](https://snyk.io/test/github/amkisko/activeadmin_favorites.rb)
+- [Codecov](https://app.codecov.io/github/amkisko/activeadmin_favorites.rb)
+- [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/amkisko/activeadmin_favorites.rb)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Sponsors
+
+Sponsored by [Kisko Labs](https://www.kiskolabs.com).
+
+<a href="https://www.kiskolabs.com">
+  <img src="kisko.svg" width="200" alt="Sponsored by Kisko Labs" />
+</a>

data/SECURITY.md

@@ -0,0 +1,27 @@
+# SECURITY
+
+## Reporting a vulnerability
+
+Do NOT open a public GitHub issue for security vulnerabilities.
+
+Email security details to: security@kiskolabs.com
+
+Include: description, steps to reproduce, potential impact, and suggested fix (if available).
+
+### Response timeline
+
+- We will acknowledge receipt of your report
+- We will provide an initial assessment
+- We will keep you informed of our progress and resolution timeline
+
+### Disclosure policy
+
+- We will work with you to understand and resolve the issue
+- We will credit you for the discovery (unless you prefer to remain anonymous)
+- We will publish a security advisory after the vulnerability is patched
+- We will coordinate public disclosure with you
+
+## Automation security
+
+- Context isolation: it is strictly forbidden to include production credentials, API keys, or personally identifiable information in prompts sent to third-party LLMs or automation services.
+- Supply chain: all automated dependencies must be verified.

data/activeadmin_favorites.gemspec

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "lib/activeadmin/favorites/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "activeadmin_favorites"
+  spec.version = ActiveAdmin::Favorites::VERSION
+  spec.authors = ["Andrei Makarov"]
+  spec.email = ["contact@kiskolabs.com"]
+
+  spec.summary = "Favorites and view lens personalization for ActiveAdmin 4"
+  spec.description = "Saved filter bookmarks, per-resource layout preferences, and a cogwheel personalization UI for ActiveAdmin index and show pages."
+  spec.license = "MIT"
+  spec.platform = Gem::Platform::RUBY
+  spec.required_ruby_version = ">= 3.4"
+
+  repository_url = "https://github.com/amkisko/activeadmin_favorites.rb"
+
+  spec.homepage = repository_url
+  spec.metadata = {
+    "homepage_uri" => repository_url,
+    "source_code_uri" => "#{repository_url}/tree/main",
+    "changelog_uri" => "#{repository_url}/blob/main/CHANGELOG.md",
+    "bug_tracker_uri" => "#{repository_url}/issues",
+    "documentation_uri" => "#{repository_url}#readme",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    %w[
+      CHANGELOG.md
+      CODE_OF_CONDUCT.md
+      CONTRIBUTING.md
+      GOVERNANCE.md
+      LICENSE.md
+      README.md
+      SECURITY.md
+      activeadmin_favorites.gemspec
+    ].select { |path| File.file?(path) } +
+      Dir["{app,config,db,lib,sig}/**/*"]
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activeadmin", ">= 4.0.0.beta13", "< 5"
+  spec.add_dependency "importmap-rails"
+  spec.add_dependency "rails", ">= 7.2"
+
+  spec.add_development_dependency "factory_bot", "~> 6"
+  spec.add_development_dependency "appraisal", "~> 2"
+  spec.add_development_dependency "bundler-audit", "~> 0.9"
+  spec.add_development_dependency "bundler", ">= 2"
+  spec.add_development_dependency "polyrun", ">= 2.2.0"
+  spec.add_development_dependency "prosopite", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13"
+  spec.add_development_dependency "rspec", "~> 3"
+  spec.add_development_dependency "rspec-rails", ">= 6"
+  spec.add_development_dependency "sqlite3", ">= 1"
+  spec.add_development_dependency "rubocop-rails", "~> 2.34"
+  spec.add_development_dependency "rubocop-rspec", "~> 3.8"
+  spec.add_development_dependency "rubocop-thread_safety", "~> 0.7"
+  spec.add_development_dependency "standard", "~> 1.52"
+  spec.add_development_dependency "standard-custom", "~> 1.0"
+  spec.add_development_dependency "standard-performance", "~> 1.8"
+  spec.add_development_dependency "standard-rails", "~> 1.5"
+  spec.add_development_dependency "standard-rspec", "~> 0.3"
+  spec.add_development_dependency "rbs", "~> 4"
+end

data/app/assets/controllers/activeadmin_favorites/personalization_controller.js

@@ -0,0 +1,199 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["menu", "catalogGroups", "visibilityCheckbox"]
+  static values = {
+    resourceKey: String,
+    actionName: String,
+    path: String,
+    catalogElementId: String,
+    hidden: Object,
+    groupLabels: Object,
+    emptyCatalogLabel: String,
+    updateUrl: String,
+    resetUrl: String,
+    saveLensUrl: String,
+    favoritesUrl: String
+  }
+
+  connect() {
+    this.catalogLoaded = false
+  }
+
+  prepareMenu() {
+    if (!this.catalogLoaded) {
+      this.renderCatalogGroups()
+      this.catalogLoaded = true
+    }
+
+    this.syncCheckboxesFromHidden()
+  }
+
+  catalogEntries() {
+    const element = document.getElementById(this.catalogElementIdValue)
+    if (!element) return []
+
+    try {
+      return JSON.parse(element.textContent)
+    } catch (_error) {
+      return []
+    }
+  }
+
+  escapeHtml(value) {
+    return String(value)
+      .replaceAll("&", "&")
+      .replaceAll("<", "&lt;")
+      .replaceAll(">", "&gt;")
+      .replaceAll('"', "&quot;")
+      .replaceAll("'", "&#39;")
+  }
+
+  renderCatalogGroups() {
+    const grouped = this.catalogEntries().reduce((result, entry) => {
+      result[entry.group] ||= []
+      result[entry.group].push(entry)
+      return result
+    }, {})
+
+    const groups = Object.keys(grouped)
+    if (groups.length === 0) {
+      this.catalogGroupsTarget.innerHTML = `<p class="text-sm text-gray-600 dark:text-gray-300">${this.escapeHtml(this.emptyCatalogLabelValue)}</p>`
+      return
+    }
+
+    this.catalogGroupsTarget.innerHTML = groups.map((group) => {
+      const label = this.escapeHtml(this.groupLabelsValue[group] || group.replace(/_/g, " "))
+      const items = grouped[group].map((entry) => {
+        const entryLabel = this.escapeHtml(entry.label)
+        const entryGroup = this.escapeHtml(entry.group)
+        const entryId = this.escapeHtml(entry.id)
+        return `
+          <li>
+            <label class="inline-flex items-center gap-2 text-sm">
+              <input
+                type="checkbox"
+                checked
+                class="rounded border-gray-300 dark:border-white/20"
+                data-group="${entryGroup}"
+                data-entry-id="${entryId}"
+                data-${this.identifier}-target="visibilityCheckbox"
+              />
+              <span>${entryLabel}</span>
+            </label>
+          </li>
+        `
+      }).join("")
+
+      return `
+        <div class="mb-4">
+          <h4 class="text-xs font-medium uppercase tracking-wide text-gray-500 dark:text-gray-400 mb-2">${label}</h4>
+          <ul class="space-y-2 max-h-40 overflow-y-auto">${items}</ul>
+        </div>
+      `
+    }).join("")
+  }
+
+  syncCheckboxesFromHidden() {
+    const hidden = this.hiddenValue || {}
+    this.visibilityCheckboxTargets.forEach((checkbox) => {
+      const group = checkbox.dataset.group
+      const entryId = checkbox.dataset.entryId
+      const hiddenIds = hidden[group] || []
+      checkbox.checked = !hiddenIds.includes(entryId)
+    })
+  }
+
+  currentLayout() {
+    const hidden = {}
+    this.visibilityCheckboxTargets.forEach((checkbox) => {
+      const group = checkbox.dataset.group
+      const entryId = checkbox.dataset.entryId
+      if (!checkbox.checked) {
+        hidden[group] ||= []
+        hidden[group].push(entryId)
+      }
+    })
+
+    return {
+      version: 1,
+      hidden
+    }
+  }
+
+  async saveDefault() {
+    await this.submitLayout(this.updateUrlValue, "PATCH")
+  }
+
+  async resetDefault() {
+    const body = new FormData()
+    body.append("resource_key", this.resourceKeyValue)
+    body.append("view_lens_action", this.actionNameValue)
+    body.append("_method", "delete")
+    body.append("authenticity_token", this.csrfToken())
+
+    const response = await fetch(this.resetUrlValue, {
+      method: "POST",
+      body,
+      headers: { Accept: "text/html" }
+    })
+
+    if (response.redirected) {
+      window.location.href = response.url
+    } else if (response.ok) {
+      window.location.reload()
+    }
+  }
+
+  async saveLensFavorite() {
+    const name = window.prompt(this.promptLabel())
+    if (!name) return
+
+    const body = new FormData()
+    body.append("name", name)
+    body.append("resource_key", this.resourceKeyValue)
+    body.append("view_lens_action", this.actionNameValue)
+    body.append("path", this.pathValue)
+    body.append("layout", JSON.stringify(this.currentLayout()))
+    body.append("authenticity_token", this.csrfToken())
+
+    const response = await fetch(this.saveLensUrlValue, {
+      method: "POST",
+      body,
+      headers: { Accept: "text/html" }
+    })
+
+    if (response.redirected) {
+      window.location.href = response.url
+    }
+  }
+
+  async submitLayout(url, method) {
+    const body = new FormData()
+    body.append("resource_key", this.resourceKeyValue)
+    body.append("view_lens_action", this.actionNameValue)
+    body.append("layout", JSON.stringify(this.currentLayout()))
+    body.append("authenticity_token", this.csrfToken())
+    if (method !== "POST") body.append("_method", method.toLowerCase())
+
+    const response = await fetch(url, {
+      method: method === "PATCH" ? "POST" : method,
+      body,
+      headers: { Accept: "text/html" }
+    })
+
+    if (response.redirected) {
+      window.location.href = response.url
+    } else if (response.ok) {
+      window.location.reload()
+    }
+  }
+
+  csrfToken() {
+    return document.querySelector("meta[name='csrf-token']")?.content
+  }
+
+  promptLabel() {
+    return this.element.dataset.promptLabel || "Name for lens favorite"
+  }
+}

data/app/models/active_admin/favorites/application_record.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Favorites
+    class ApplicationRecord < ::ApplicationRecord
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/active_admin/favorites/combined_favorite.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Favorites
+    class CombinedFavorite < Favorite
+      validates :layout, presence: true
+    end
+  end
+end

data/app/models/active_admin/favorites/favorite/macro_builder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Favorites
+    class Favorite
+      class MacroBuilder
+        def self.from_template_assignments(assignments)
+          assignment_rows(assignments).filter_map do |assignment|
+            next unless ActiveModel::Type::Boolean.new.cast(assignment["enabled"])
+
+            attribute = assignment["attribute"].to_s
+            template_name = assignment["name"].to_s
+            next if attribute.blank? || template_name.blank?
+
+            {
+              "type" => "template",
+              "name" => template_name,
+              "attribute" => attribute
+            }
+          end
+        end
+
+        def self.from_json(json_string)
+          parsed = JSON.parse(json_string)
+          raise JSON::ParserError unless parsed.is_a?(Array)
+
+          parsed
+        end
+
+        def self.template(attribute, name:)
+          [{"type" => "template", "name" => name.to_s, "attribute" => attribute.to_s}]
+        end
+
+        def self.assignment_rows(assignments)
+          return [] if assignments.blank?
+
+          HashCoercion.assignment_values(assignments)
+        end
+        private_class_method :assignment_rows
+      end
+    end
+  end
+end