activeadmin-autocompletes 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25930eaa8bc6450243eae296499fac843526243dbbc0dba8e3e9c548c13a5104
+  data.tar.gz: 4ea216c7a7e4b2527075c4479d7e4293c67bd60de20fe26b52c0280a8640fa03
+SHA512:
+  metadata.gz: b16837f4267a1f7110c9d7160a8a16a1c7f12e4cca3727906c2ab915ef22cbb150e376900b374a5b099380a81d0615fdcc03ecf7490ebf8b3f891acaa317ae5b
+  data.tar.gz: 047d792fe35bd69259fe22e82d7fb91b2ca7e6609223dc3f48cb696802d00a45ec95bff2139a7675dbb66222602f0f2689413d8fd1df1455036559e9ace0cfaa

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# CHANGELOG
+
+## 0.3.0 (2026-11-12)
+
+- Add `params:` and `param_fields:` on autocomplete inputs so options requests can carry static keys and live sibling-field values
+- Clear the current selection when a watched `param_fields` source changes
+- Add optional `page_size:` on inputs (clamped to 1..50)
+- Add `fi` and `sv` placeholders for the search field
+- Prove importmap pin and field partial resolution in engine specs
+- Extract ActiveAdmin lazy autocomplete (filters, form inputs, Stimulus typeahead, multi-select chips) into a standalone gem
+- Add multi-select chips mode (`multiple: true`) for form and filter autocomplete inputs
+- Clamp option `limit` to 1..50 and query string to 200 bytes (server and Stimulus)
+- Align Stimulus `hasMore` pagination with the clamped page size
+- Document host `authorize! :index` contract and multi-endpoint `action:` / `params` usage
+- Pressure binding and L1 load ceilings for the Ruby payload shaping path
+- Rails dummy + request specs for autocomplete options endpoints and filter index rendering

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,26 @@
+# Code of Conduct
+
+## Pledge
+
+Participation is a harassment-free experience. Treat each other with respect. Keep private context private.
+
+## Expected behavior
+
+- Engage with genuine curiosity. Admit uncertainty.
+- Own every line you submit, including generated code.
+- Correct errors politely.
+- Use language that welcomes people and respects identity and privacy.
+
+## Unacceptable behavior
+
+- Harassment, trolling, or insulting comments, public or private.
+- Using jargon or volume, including automated spam, to silence others.
+- Sharing others' data or personal context without permission.
+
+## Automation
+
+You remain responsible for bugs, security holes, and bias in generated artifacts you submit.
+
+## Enforcement
+
+Report abusive or harassing behavior to contact@kiskolabs.com. Reports are reviewed and investigated.

data/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing Guidelines
+
+## Automation authorship
+
+You may use AI and automation tools. You remain the author of every line you submit: review, debug, and understand the change.
+
+Keep pull requests small enough to review. Annotate non-obvious logic.
+
+Never send project secrets or private context to public models.
+
+## How to contribute
+
+### Reporting issues
+
+Verify the facts before filing. Use issue templates for goals, constraints, and reproduction steps.
+
+### Pull requests
+
+Keep one pull request to one goal. Explain why the change is needed. Run smoke tests and regression checks locally before opening the request.
+
+### Review
+
+Reviewers will ask about approach and trade-offs. Treat suggested changes as part of the work.

data/GOVERNANCE.md

@@ -0,0 +1,25 @@
+# Project Governance
+
+## Roles
+
+### Contributors
+
+Anyone who submits code, documentation, or participates in discussions. Contributors take ownership of problems they identify and follow the project's quality standards.
+
+### Maintainers
+
+Maintainers:
+
+1. Set scope and architectural direction.
+2. Review contributions (human or automated) against security and logic standards.
+3. Decide when the community is divided.
+
+## Decision making
+
+### Lazy consensus
+
+For routine changes, a proposal that draws no objection within two weeks is approved.
+
+### Maintainer approval
+
+Major architectural changes, high-risk automation integrations, or changes that affect business logic need explicit maintainer approval. A change must solve a real problem.

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,111 @@
+# activeadmin-autocompletes
+
+[![Test Status](https://github.com/amkisko/activeadmin-autocompletes.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/activeadmin-autocompletes.rb/actions/workflows/test.yml)
+
+ActiveAdmin-only support for lazy and extensible, fully configurable autocompletes for filters and inputs. Session REST JSON options, Formtastic filter/form inputs, Stimulus typeahead, and multi-select chips.
+
+## Requirements
+
+- Ruby 3.4+
+- Rails 7.2.3.2+
+- ActiveAdmin 4.0.0.beta23+
+
+## Install
+
+From RubyGems after a release:
+
+```ruby
+# Gemfile
+gem "activeadmin-autocompletes"
+```
+
+From git:
+
+```ruby
+# Gemfile
+gem "activeadmin-autocompletes", github: "amkisko/activeadmin-autocompletes.rb"
+```
+
+## Usage
+
+```ruby
+ActiveAdmin.register Thing do
+  extend ActiveAdmin::Autocompletes::FilterAutocomplete
+
+  # Default action name: :search_options → search_options_admin_things_path
+  filter_autocomplete :search do |query:, limit:, offset:|
+    Thing.search_options(query:, limit:, offset:)
+  end
+
+  # Extra endpoints: pass action: and use params from the request
+  filter_autocomplete :category_items, action: :category_item_options do |query:, limit:, offset:|
+    Item.search_options(query:, limit:, offset:, category_id: params[:category_id])
+  end
+
+  filter :city_eq,
+    as: :autocomplete,
+    label: "City",
+    url: -> { search_options_admin_things_path }
+
+  # Association id filter: hidden submitted id, visible label
+  filter :company_id_eq,
+    as: :autocomplete,
+    value_field: true,
+    label: "Company",
+    url: -> { search_options_admin_companies_path },
+    initial_label: ->(id) { Company.find_by(id: id)&.name.to_s }
+
+  # Static query params plus live sibling fields (CSS selectors)
+  filter :item_id_eq,
+    as: :autocomplete,
+    value_field: true,
+    label: "Item",
+    url: -> { category_item_options_admin_things_path },
+    page_size: 10,
+    params: {scope: "active"},
+    param_fields: {category_id: "#q_category_id_eq"},
+    initial_label: ->(id) { Item.find_by(id: id)&.name.to_s }
+
+  # Multi-select chips on forms (and filters when multiple: true)
+  form do |f|
+    f.input :tag_ids,
+      as: :autocomplete,
+      multiple: true,
+      value_field: true,
+      url: -> { search_options_admin_tags_path },
+      initial_labels: ->(id) { Tag.find_by(id: id)&.name.to_s }
+  end
+end
+```
+
+Options endpoint must return JSON `[{ "label" => "...", "value" => "..." }, ...]` (optional `id` is accepted as the submitted value).
+
+Input options:
+
+- `params:` - hash or callable; merged into every options request as query keys
+- `param_fields:` - hash of query key => CSS selector; live values read from those fields on each fetch; changing a watched field clears the current selection
+- `page_size:` - client page size (clamped to 1..50, default 20)
+
+### Authorization and bounds
+
+Every options `collection_action` calls `authorize! :index, config.resource_class`. Hosts that need a finer permission must wrap the block or authorize in the host policy for `index?` on that resource.
+
+Server clamps `limit` to 1..50 and `q` to 200 bytes. The Stimulus controller applies the same page-size and query bounds and uses the clamped limit for `hasMore` pagination. Host search blocks must stay indexed and bounded themselves; the gem does not rewrite queries or add indexes.
+
+## Assets
+
+The engine pins the Stimulus controller on `ActiveAdmin.importmap`. Host should watch:
+
+```ruby
+ActiveAdmin::Autocompletes::Engine.root.join("app/assets")
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec appraisal install
+make test
+```
+
+Maintainers publish with `make release` (`usr/bin/release.rb`).

data/SECURITY.md

@@ -0,0 +1,25 @@
+# SECURITY
+
+## Reporting a Vulnerability
+
+Email security details to: security@kiskolabs.com
+
+Send the report only to that address. Include description, steps to reproduce, potential impact, and a suggested fix when you have one.
+
+### 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
+
+- Keep production credentials, API keys, and personal data out of prompts sent to third-party models or automation services.
+- Verify automated dependencies.

data/activeadmin-autocompletes.gemspec

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "lib/activeadmin/autocompletes/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "activeadmin-autocompletes"
+  spec.version = ActiveAdmin::Autocompletes::VERSION
+  spec.authors = ["Andrei Makarov"]
+  spec.email = ["contact@kiskolabs.com"]
+
+  spec.summary = "Lazy REST autocomplete inputs and filters for ActiveAdmin"
+  spec.description = "ActiveAdmin-only support for lazy and extensible, fully configurable autocompletes for filters and inputs. Collection-action JSON options, Formtastic filter/form inputs, Stimulus typeahead, and multi-select chips."
+  spec.license = "MIT"
+  spec.platform = Gem::Platform::RUBY
+  spec.required_ruby_version = ">= 3.4.0"
+
+  repository_url = "https://github.com/amkisko/activeadmin-autocompletes.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",
+    "allowed_push_host" => "https://rubygems.org",
+    "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-autocompletes.gemspec
+    ].select { |path| File.file?(path) } +
+      Dir["{app,config,lib,sig}/**/*"]
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activeadmin", ">= 4.0.0.beta23", "< 5"
+  spec.add_dependency "importmap-rails"
+  spec.add_dependency "rails", ">= 7.2.3.2"
+
+  spec.add_development_dependency "appraisal", "~> 2"
+  spec.add_development_dependency "bundler", ">= 2"
+  spec.add_development_dependency "bundler-audit", "~> 0.9"
+  spec.add_development_dependency "polyrun", ">= 3.0.0"
+  spec.add_development_dependency "rake", "~> 13"
+  spec.add_development_dependency "rbs", "~> 4"
+  spec.add_development_dependency "rspec", "~> 3"
+  spec.add_development_dependency "rspec-rails", ">= 6"
+  spec.add_development_dependency "sqlite3", ">= 2.10.2"
+  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-rspec", "~> 0.3"
+end

data/app/assets/controllers/activeadmin_autocompletes/filter_autocomplete_controller.js

@@ -0,0 +1,324 @@
+import { Controller } from "@hotwired/stimulus";
+
+const OPTION_CLASS =
+  "cursor-pointer px-3 py-2 hover:bg-gray-100 dark:hover:bg-gray-800";
+const OPTION_ACTIVE_CLASS = "bg-gray-100 dark:bg-gray-800";
+const CHIP_CLASS =
+  "inline-flex items-center gap-1 rounded-full border border-gray-300 bg-gray-50 px-2 py-0.5 text-sm dark:border-gray-600 dark:bg-gray-800";
+const CONTROLLER = "activeadmin-autocompletes--filter-autocomplete";
+
+export default class extends Controller {
+  static targets = ["query", "list", "value", "chips", "selected"];
+  static values = {
+    url: String,
+    pageSize: { type: Number, default: 20 },
+    multiple: { type: Boolean, default: false },
+    params: { type: Object, default: {} },
+    paramFields: { type: Object, default: {} },
+  };
+
+  static MAX_PAGE_SIZE = 50;
+  static MAX_QUERY_CHARS = 200;
+  static MAX_LIST_ITEMS = 100;
+
+  connect() {
+    this.activeIndex = -1;
+    this.offset = 0;
+    this.hasMore = false;
+    this.loading = false;
+    this.lastQuery = null;
+    this.selected = this.readSelected();
+    this.renderChips();
+    this.boundClearOnDependency = () => this.clearForDependency();
+    this.paramFieldElements().forEach((element) => {
+      element.addEventListener("change", this.boundClearOnDependency);
+      element.addEventListener("input", this.boundClearOnDependency);
+    });
+  }
+
+  disconnect() {
+    clearTimeout(this.timeout);
+    this.abortController?.abort();
+    this.paramFieldElements().forEach((element) => {
+      element.removeEventListener("change", this.boundClearOnDependency);
+      element.removeEventListener("input", this.boundClearOnDependency);
+    });
+  }
+
+  search() {
+    clearTimeout(this.timeout);
+    this.timeout = setTimeout(() => this.fetchResults({ reset: true }), 250);
+    if (!this.multipleValue && this.hasValueTarget) this.valueTarget.value = "";
+  }
+
+  open() {
+    this.fetchResults({ reset: true });
+  }
+
+  loadMore() {
+    if (!this.hasMore || this.loading || this.listTarget.classList.contains("hidden")) {
+      return;
+    }
+
+    const { scrollTop, scrollHeight, clientHeight } = this.listTarget;
+    if (scrollTop + clientHeight < scrollHeight - 24) return;
+
+    this.fetchResults({ reset: false });
+  }
+
+  navigate(event) {
+    if (event.key === "Backspace" && this.multipleValue && !this.queryTarget.value) {
+      const last = this.selected[this.selected.length - 1];
+      if (last) this.removeValue(last.value);
+      return;
+    }
+
+    if (this.listTarget.classList.contains("hidden")) return;
+
+    const options = this.optionElements();
+    if (options.length === 0) return;
+
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      this.activeIndex = Math.min(this.activeIndex + 1, options.length - 1);
+      this.highlight(options);
+    } else if (event.key === "ArrowUp") {
+      event.preventDefault();
+      this.activeIndex = Math.max(this.activeIndex - 1, 0);
+      this.highlight(options);
+    } else if (event.key === "Enter" && this.activeIndex >= 0) {
+      event.preventDefault();
+      options[this.activeIndex].dispatchEvent(
+        new MouseEvent("mousedown", { bubbles: true })
+      );
+    } else if (event.key === "Escape") {
+      this.close();
+    }
+  }
+
+  async fetchResults({ reset }) {
+    const query = this.queryTarget.value.trim().slice(0, this.constructor.MAX_QUERY_CHARS);
+    if (reset) {
+      this.offset = 0;
+      this.hasMore = false;
+      this.lastQuery = query;
+      this.activeIndex = -1;
+    } else if (query !== this.lastQuery) {
+      return;
+    }
+
+    this.loading = true;
+    this.abortController?.abort();
+    this.abortController = new AbortController();
+
+    try {
+      const url = new URL(this.urlValue, window.location.origin);
+      if (query) url.searchParams.set("q", query);
+      url.searchParams.set("offset", String(this.offset));
+      const limit = Math.min(
+        Math.max(Number(this.pageSizeValue) || 20, 1),
+        this.constructor.MAX_PAGE_SIZE
+      );
+      url.searchParams.set("limit", String(limit));
+      this.applyExtraParams(url);
+
+      const response = await fetch(url.toString(), {
+        headers: { Accept: "application/json" },
+        credentials: "same-origin",
+        signal: this.abortController.signal,
+      });
+
+      if (!response.ok) {
+        if (reset) this.close();
+        return;
+      }
+
+      const items = await response.json();
+      const selectedValues = new Set(this.selected.map((item) => String(item.value)));
+      const visible = items.filter((item) => !selectedValues.has(String(item.value ?? item.id ?? item.label)));
+      this.renderList(visible, { append: !reset });
+      this.hasMore = items.length >= limit;
+      this.offset += items.length;
+      this.setExpanded(true);
+    } catch (error) {
+      if (error.name !== "AbortError" && reset) this.close();
+    } finally {
+      this.loading = false;
+    }
+  }
+
+  applyExtraParams(url) {
+    Object.entries(this.paramsValue || {}).forEach(([key, value]) => {
+      if (value == null || value === "") return;
+      url.searchParams.set(key, String(value));
+    });
+
+    Object.entries(this.paramFieldsValue || {}).forEach(([key, selector]) => {
+      if (!selector) return;
+      const element = document.querySelector(selector);
+      const value = element?.value;
+      if (value == null || value === "") return;
+      url.searchParams.set(key, String(value));
+    });
+  }
+
+  paramFieldElements() {
+    return Object.values(this.paramFieldsValue || {})
+      .filter(Boolean)
+      .map((selector) => document.querySelector(selector))
+      .filter(Boolean);
+  }
+
+  clearForDependency() {
+    if (this.multipleValue) {
+      this.selected = [];
+      this.syncSelectedInputs();
+      this.renderChips();
+    } else if (this.hasValueTarget) {
+      this.valueTarget.value = "";
+      this.queryTarget.value = "";
+    } else {
+      this.queryTarget.value = "";
+    }
+    this.close();
+  }
+
+  renderList(items, { append }) {
+    if (!append) this.listTarget.replaceChildren();
+
+    const fragment = document.createDocumentFragment();
+    items.forEach((item) => {
+      const option = document.createElement("li");
+      option.className = OPTION_CLASS;
+      option.dataset.action = `mousedown->${CONTROLLER}#select`;
+      option.dataset.value = item.value ?? item.id ?? item.label;
+      option.dataset.label = item.label ?? item.value ?? item.id;
+      option.textContent = item.label ?? item.value ?? item.id;
+      option.setAttribute("role", "option");
+      fragment.appendChild(option);
+    });
+    this.listTarget.appendChild(fragment);
+    this.trimListWindow();
+
+    if (this.listTarget.children.length === 0) {
+      this.close();
+      return;
+    }
+
+    this.listTarget.classList.remove("hidden");
+  }
+
+  trimListWindow() {
+    const max = this.constructor.MAX_LIST_ITEMS;
+    while (this.listTarget.children.length > max) {
+      this.listTarget.firstElementChild.remove();
+      if (this.activeIndex >= 0) this.activeIndex -= 1;
+    }
+  }
+
+  select(event) {
+    event.preventDefault();
+    const { value, label } = event.currentTarget.dataset;
+    if (this.multipleValue) {
+      this.addValue(value, label || value);
+      this.queryTarget.value = "";
+      this.close();
+      this.queryTarget.focus();
+      return;
+    }
+
+    if (this.hasValueTarget) {
+      this.valueTarget.value = value || "";
+      this.queryTarget.value = label || value || "";
+    } else {
+      this.queryTarget.value = value || "";
+    }
+    this.close();
+  }
+
+  removeChip(event) {
+    event.preventDefault();
+    this.removeValue(event.currentTarget.dataset.value);
+  }
+
+  addValue(value, label) {
+    const key = String(value);
+    if (!value || this.selected.some((item) => item.value === key)) return;
+    this.selected.push({ value: key, label: label || key });
+    this.syncSelectedInputs();
+    this.renderChips();
+  }
+
+  removeValue(value) {
+    const key = String(value);
+    const index = this.selected.findIndex((item) => item.value === key);
+    if (index < 0) return;
+    this.selected.splice(index, 1);
+    this.syncSelectedInputs();
+    this.renderChips();
+  }
+
+  readSelected() {
+    if (!this.multipleValue) return [];
+    return this.selectedTargets.map((input) => ({
+      value: input.value,
+      label: input.dataset.label || input.value,
+    }));
+  }
+
+  syncSelectedInputs() {
+    this.selectedTargets.forEach((input) => input.remove());
+    const fieldName = this.element.dataset.fieldName;
+    if (!fieldName) return;
+
+    this.selected.forEach((item) => {
+      const input = document.createElement("input");
+      input.type = "hidden";
+      input.name = fieldName;
+      input.value = item.value;
+      input.dataset.label = item.label;
+      input.setAttribute(`data-${CONTROLLER}-target`, "selected");
+      this.element.appendChild(input);
+    });
+  }
+
+  renderChips() {
+    if (!this.multipleValue || !this.hasChipsTarget) return;
+    this.chipsTarget.replaceChildren();
+    this.selected.forEach((item) => {
+      const chip = document.createElement("span");
+      chip.className = CHIP_CLASS;
+      const text = document.createElement("span");
+      text.textContent = item.label;
+      const remove = document.createElement("button");
+      remove.type = "button";
+      remove.textContent = "×";
+      remove.setAttribute("aria-label", `Remove ${item.label}`);
+      remove.dataset.value = item.value;
+      remove.dataset.action = `click->${CONTROLLER}#removeChip`;
+      chip.append(text, remove);
+      this.chipsTarget.appendChild(chip);
+    });
+  }
+
+  close() {
+    this.listTarget.classList.add("hidden");
+    this.listTarget.replaceChildren();
+    this.activeIndex = -1;
+    this.setExpanded(false);
+  }
+
+  optionElements() {
+    return Array.from(this.listTarget.querySelectorAll('[role="option"]'));
+  }
+
+  highlight(options) {
+    options.forEach((option, index) => {
+      option.classList.toggle(OPTION_ACTIVE_CLASS, index === this.activeIndex);
+    });
+  }
+
+  setExpanded(expanded) {
+    this.queryTarget.setAttribute("aria-expanded", expanded ? "true" : "false");
+  }
+}