admin_suite 0.2.7 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5150c2ac986138055644b1e6f52c61ee774efc62e27a951a34d4ca9943fe7d8
-  data.tar.gz: 57729f5a0e760f26111c7f73aeec78a7493a1b849ba12bd50c992ebfbaf6c034
+  metadata.gz: f50f5a24977b7bc8284ee051fb3d9d1746b49a1ab8d9ade00d917bf0a8ff412b
+  data.tar.gz: 6e32362f8fe763980b83fa34910b21020d7bdca7918afb5d63084aae7e80d72e
 SHA512:
-  metadata.gz: e99ac448e983647cb570ae875e0681e138895c7783a6538ee6aa0b898e93001c3dd65b8dcf6b882885c83ef35042f55c29ef2e75f00d77025af6de58254be7b4
-  data.tar.gz: df3a565311c4a10df7603eaa776bf1a3e4ed3f2cea6dc6445b3702986887c900f13c0af272af4bb006bb9af921b8d0ec545b8f049b12dbb2078cd77d69eddb2d
+  metadata.gz: b980579e952dc4ec9cd1cd56dab61219f9320e810df0697a97ad42031e08fa59793c893adfdcd00e7d0ab7449468ae7d02a886f2dd6a3406c65bf5c750a28c3f
+  data.tar.gz: 603fdf2522093c9aba2427286e6573515a75d3016367dde07d3a74661bc7e15ffe95b1b388258c3398cc4d6583b85ef7c9ace18cc55e118b116344835802dfdc

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.9] - 2026-07-14
+
+### Added
+
+- Read-only resource support, server-side filter defaults, and filtered-scope statistics.
+
+## [0.2.8] - 2026-03-23
+
+### Added
+
+- **Dependent searchable select** field type (`:dependent_select`) — cascading dropdowns where a child field's options filter by the selected parent value. Uses `parent_field:` option and `[label, value, group]` collection triples.
+- **Stimulus entry point** (`admin_suite_application.js`) — automatically imports and registers all 12 AdminSuite Stimulus controllers on `window.Stimulus`.
+- `parent_field` attribute on `FieldDefinition` for linking dependent fields.
+
+### Fixed
+
+- **Stimulus controllers not loading** — engine controllers were pinned via importmap but never imported. Added explicit entry point in layout via `<script type="module">`.
+- **Searchable select change propagation** — `applyOption()` now dispatches a `change` event on the hidden input, enabling dependent field chaining.
+
+### Security
+
+- New `dependent_searchable_select_controller.js` uses safe DOM construction (`createElement`/`textContent`/`appendChild`) instead of `innerHTML` template literals.
+
 ## [0.2.6] - 2026-02-21
 
 ### Added
@@ -21,4 +44,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial extraction of the AdminSuite Rails engine.
 - Resource/portal DSL, docs viewer, and theming primitives.
 - Isolated gem test suite with a dummy Rails app.
-

data/CONTRIBUTING.md

@@ -12,7 +12,7 @@ Thank you for your interest in contributing to AdminSuite!
 
 ## Development
 
-See `docs/development.md` for detailed information on:
+See `../_vault/products/admin_suite/docs/development.md` for detailed information on:
 - Setting up your development environment
 - Running tests
 - Code style guidelines
@@ -36,7 +36,7 @@ The CI workflow runs automatically on every pull request.
 
 ## Releasing
 
-See `docs/releasing.md` for information on how releases are managed.
+See `../_vault/products/admin_suite/docs/releasing.md` for information on how releases are managed.
 
 Releases are automated via GitHub Actions when changes are merged to `main` with a version bump.
 

data/README.md

@@ -15,21 +15,9 @@ across other products.
 
 ## Documentation
 
-Start here:
-
-- `docs/README.md` (index)
-
-Read more:
-
-- `docs/installation.md`
-- `docs/configuration.md`
-- `docs/portals.md`
-- `docs/resources.md`
-- `docs/fields.md`
-- `docs/actions.md`
-- `docs/theming.md`
-- `docs/docs_viewer.md`
-- `docs/troubleshooting.md`
+Canonical AdminSuite documentation lives in the TechWright vault at
+`../_vault/products/admin_suite/docs/`. This repo intentionally has no root
+`docs/` tree or docs symlink.
 
 ## Quickstart
 
@@ -67,7 +55,7 @@ AdminSuite.configure do |config|
 end
 ```
 
-Read more: `docs/configuration.md`
+Read more: `../_vault/products/admin_suite/docs/configuration.md`
 
 ### Add portals (navigation metadata)
 
@@ -80,7 +68,7 @@ AdminSuite.configure do |config|
 end
 ```
 
-Read more: `docs/portals.md`
+Read more: `../_vault/products/admin_suite/docs/portals.md`
 
 ### Add a resource
 
@@ -119,25 +107,23 @@ module Admin
 end
 ```
 
-Read more: `docs/resources.md` and `docs/fields.md`
+Read more: `../_vault/products/admin_suite/docs/resources.md` and `../_vault/products/admin_suite/docs/fields.md`
 
 ### Add docs (optional)
 
-Create markdown files in your host app:
-
-- `docs/*.md` (or set `config.docs_path`)
+Set `config.docs_path` to an explicit documentation source. TechWright host apps point this at their canonical `_vault/products/<product>/docs/` directory; they do not create repo `docs/` trees.
 
 Then visit:
 
 - `/internal/admin/docs`
 
-Read more: `docs/docs_viewer.md`
+Read more: `../_vault/products/admin_suite/docs/docs_viewer.md`
 
 ## Contributing
 
 See:
 
 - `CONTRIBUTING.md`
-- `docs/development.md`
-- `docs/releasing.md`
+- `../_vault/products/admin_suite/docs/development.md`
+- `../_vault/products/admin_suite/docs/releasing.md`
 

data/app/controllers/admin_suite/resources_controller.rb

@@ -5,14 +5,16 @@ module AdminSuite
     include Pagy::Backend
     include Pagy::Frontend
 
+    before_action :enforce_read_only!, only: %i[new create edit update destroy]
     before_action :set_resource, if: -> { params[:id].present? && !%w[index new create].include?(action_name) }
 
     helper_method :resource_config, :resource_class, :resource, :collection, :current_portal, :resource_name
 
     # GET /:portal/:resource_name
     def index
-      @stats = calculate_stats if resource_config&.index_config&.stats_list&.any?
-      @pagy, @collection = paginate_collection(filtered_collection)
+      scope = filtered_collection
+      @stats = calculate_stats(scope) if resource_config&.index_config&.stats_list&.any?
+      @pagy, @collection = paginate_collection(scope)
     end
 
     # GET /:portal/:resource_name/:id
@@ -181,11 +183,15 @@ module AdminSuite
       pagy(scope, items: per_page)
     end
 
-    def calculate_stats
+    def calculate_stats(scope)
       resource_config.index_config.stats_list.map do |stat_def|
         value =
           begin
-            stat_def.calculator.call
+            if stat_def.calculator.arity.zero?
+              stat_def.calculator.call
+            else
+              stat_def.calculator.call(scope)
+            end
           rescue StandardError
             "N/A"
           end
@@ -193,6 +199,10 @@ module AdminSuite
       end
     end
 
+    def enforce_read_only!
+      head :not_found if resource_config&.read_only?
+    end
+
     def find_action(name)
       resource_config&.actions_config&.member_actions&.find { |a| a.name == name }
     end

data/app/helpers/admin_suite/base_helper.rb

@@ -1117,6 +1117,62 @@ module AdminSuite
       end
     end
 
+    def render_dependent_searchable_select(_f, field, resource)
+      param_key = resource.class.model_name.param_key
+      current_value = resource.public_send(field.name)
+      collection = field.collection.is_a?(Proc) ? field.collection.call : field.collection
+
+      # Collection format: [[label, value, group], ...] — triples with group for filtering
+      all_options_json = if collection.is_a?(Array)
+        collection.map { |opt|
+          if opt.is_a?(Array) && opt.size >= 3
+            { value: opt[1], label: opt[0], group: opt[2] }
+          elsif opt.is_a?(Array)
+            { value: opt[1], label: opt[0] }
+          else
+            { value: opt, label: opt.to_s.humanize }
+          end
+        }.to_json
+      else
+        "[]"
+      end
+
+      parent_selector = if field.parent_field
+        "[name=\"#{param_key}[#{field.parent_field}]\"]"
+      else
+        ""
+      end
+
+      current_label = if current_value.present? && collection.is_a?(Array)
+        match = collection.find { |opt| opt.is_a?(Array) ? opt[1].to_s == current_value.to_s : opt.to_s == current_value.to_s }
+        match.is_a?(Array) ? match[0] : match.to_s
+      else
+        current_value
+      end
+
+      content_tag(:div,
+        data: {
+          controller: "admin-suite--dependent-searchable-select",
+          "admin-suite--dependent-searchable-select-all-options-value": all_options_json,
+          "admin-suite--dependent-searchable-select-parent-selector-value": parent_selector
+        },
+        class: "relative") do
+        concat(hidden_field_tag("#{param_key}[#{field.name}]", current_value,
+          data: { "admin-suite--dependent-searchable-select-target": "input" }))
+        concat(text_field_tag(nil, current_label,
+          class: "form-input w-full",
+          placeholder: field.placeholder || "Search...",
+          autocomplete: "off",
+          data: {
+            "admin-suite--dependent-searchable-select-target": "search",
+            action: "input->admin-suite--dependent-searchable-select#search focus->admin-suite--dependent-searchable-select#open keydown->admin-suite--dependent-searchable-select#keydown"
+          }))
+        concat(content_tag(:div, "",
+          class: "absolute z-40 w-full mt-1 bg-white dark:bg-slate-800 border border-slate-200 dark:border-slate-700 rounded-lg shadow-lg hidden max-h-60 overflow-y-auto",
+          data: { "admin-suite--dependent-searchable-select-target": "dropdown" }))
+      end
+    end
+
     def render_multi_select(_f, field, resource)
       param_key = resource.class.model_name.param_key
       current_values =

data/app/javascript/admin_suite_application.js

@@ -0,0 +1,44 @@
+import { Application } from "@hotwired/stimulus"
+
+// Reuse the host app's Stimulus application if available, otherwise start a new one
+const application = window.Stimulus || Application.start()
+window.Stimulus ||= application
+
+import SearchableSelectController from "controllers/admin_suite/searchable_select_controller"
+application.register("admin-suite--searchable-select", SearchableSelectController)
+
+import ToggleSwitchController from "controllers/admin_suite/toggle_switch_controller"
+application.register("admin-suite--toggle-switch", ToggleSwitchController)
+
+import TagSelectController from "controllers/admin_suite/tag_select_controller"
+application.register("admin-suite--tag-select", TagSelectController)
+
+import FileUploadController from "controllers/admin_suite/file_upload_controller"
+application.register("admin-suite--file-upload", FileUploadController)
+
+import MarkdownEditorController from "controllers/admin_suite/markdown_editor_controller"
+application.register("admin-suite--markdown-editor", MarkdownEditorController)
+
+import JsonEditorController from "controllers/admin_suite/json_editor_controller"
+application.register("admin-suite--json-editor", JsonEditorController)
+
+import CodeEditorController from "controllers/admin_suite/code_editor_controller"
+application.register("admin-suite--code-editor", CodeEditorController)
+
+import LiveFilterController from "controllers/admin_suite/live_filter_controller"
+application.register("admin-suite--live-filter", LiveFilterController)
+
+import ClickActionsController from "controllers/admin_suite/click_actions_controller"
+application.register("admin-suite--click-actions", ClickActionsController)
+
+import ClipboardController from "controllers/admin_suite/clipboard_controller"
+application.register("admin-suite--clipboard", ClipboardController)
+
+import SidebarController from "controllers/admin_suite/sidebar_controller"
+application.register("admin-suite--sidebar", SidebarController)
+
+import FlashController from "controllers/admin_suite/flash_controller"
+application.register("admin-suite--flash", FlashController)
+
+import DependentSearchableSelectController from "controllers/admin_suite/dependent_searchable_select_controller"
+application.register("admin-suite--dependent-searchable-select", DependentSearchableSelectController)

data/app/javascript/controllers/admin_suite/dependent_searchable_select_controller.js

@@ -0,0 +1,228 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Dependent Searchable Select Controller (Admin Suite)
+ *
+ * Extends searchable-select behavior with parent-field filtering.
+ * Options are filtered by `group` matching the parent field's current value.
+ *
+ * Usage:
+ *   data-controller="admin-suite--dependent-searchable-select"
+ *   data-admin-suite--dependent-searchable-select-all-options-value="<%= options.to_json %>"
+ *   data-admin-suite--dependent-searchable-select-parent-selector-value="#parent_field_id"
+ *
+ * Each option in allOptions should have: { value, label, group }
+ * The `group` field is matched against the parent field's value.
+ */
+export default class extends Controller {
+  static targets = ["input", "search", "dropdown"]
+  static values = {
+    allOptions: { type: Array, default: [] },
+    parentSelector: { type: String, default: "" },
+  }
+
+  connect() {
+    this.isOpen = false
+    this.selectedIndex = -1
+    this.parentFilteredOptions = [...this.allOptionsValue]
+
+    this.clickOutside = this.clickOutside.bind(this)
+    document.addEventListener("click", this.clickOutside)
+
+    this.bindParent()
+  }
+
+  disconnect() {
+    document.removeEventListener("click", this.clickOutside)
+
+    if (this._parentField && this._onParentChange) {
+      this._parentField.removeEventListener("change", this._onParentChange)
+    }
+  }
+
+  bindParent() {
+    const selector = this.parentSelectorValue
+    if (!selector) return
+
+    this._parentField = document.querySelector(selector)
+    if (!this._parentField) return
+
+    this._onParentChange = this.onParentChange.bind(this)
+    this._parentField.addEventListener("change", this._onParentChange)
+
+    // Apply initial filter if parent already has a value
+    if (this._parentField.value) {
+      this.filterByParent(this._parentField.value)
+    }
+  }
+
+  onParentChange() {
+    const parentValue = this._parentField ? this._parentField.value : ""
+    this.filterByParent(parentValue)
+
+    // Clear current selection if it no longer belongs to the new parent group
+    const currentValue = this.inputTarget.value
+    if (currentValue) {
+      const stillValid = this.parentFilteredOptions.some(
+        (opt) => String(opt.value) === String(currentValue),
+      )
+      if (!stillValid) {
+        this.inputTarget.value = ""
+        this.searchTarget.value = ""
+        this.inputTarget.dispatchEvent(new Event("change", { bubbles: true }))
+      }
+    }
+
+    if (this.isOpen) {
+      this.renderDropdown()
+    }
+  }
+
+  filterByParent(parentValue) {
+    if (!parentValue) {
+      this.parentFilteredOptions = [...this.allOptionsValue]
+    } else {
+      this.parentFilteredOptions = this.allOptionsValue.filter(
+        (opt) => String(opt.group) === String(parentValue),
+      )
+    }
+  }
+
+  open() {
+    this.isOpen = true
+    this.filteredOptions = [...this.parentFilteredOptions]
+    this.renderDropdown()
+    this.dropdownTarget.classList.remove("hidden")
+  }
+
+  close() {
+    this.isOpen = false
+    this.dropdownTarget.classList.add("hidden")
+    this.selectedIndex = -1
+  }
+
+  clickOutside(event) {
+    if (!this.element.contains(event.target)) {
+      this.close()
+    }
+  }
+
+  search() {
+    const query = this.searchTarget.value.toLowerCase().trim()
+
+    if (query) {
+      this.filteredOptions = this.parentFilteredOptions.filter((opt) =>
+        opt.label.toLowerCase().includes(query),
+      )
+    } else {
+      this.filteredOptions = [...this.parentFilteredOptions]
+    }
+
+    this.renderDropdown()
+
+    if (!this.isOpen) this.open()
+  }
+
+  select(event) {
+    const btn = event.currentTarget
+    const value = btn.dataset.value
+    const label = btn.dataset.label
+
+    this.inputTarget.value = value
+    this.searchTarget.value = label
+    this.close()
+    this.inputTarget.dispatchEvent(new Event("change", { bubbles: true }))
+  }
+
+  keydown(event) {
+    const opts = this.filteredOptions || this.parentFilteredOptions
+
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault()
+        if (!this.isOpen) {
+          this.filteredOptions = [...this.parentFilteredOptions]
+          this.open()
+          break
+        }
+        this.selectedIndex = Math.min(this.selectedIndex + 1, opts.length - 1)
+        this.renderDropdown()
+        break
+      case "ArrowUp":
+        event.preventDefault()
+        this.selectedIndex = Math.max(this.selectedIndex - 1, 0)
+        this.renderDropdown()
+        break
+      case "Enter":
+        event.preventDefault()
+        if (this.selectedIndex >= 0 && opts[this.selectedIndex]) {
+          const opt = opts[this.selectedIndex]
+          this.inputTarget.value = opt.value
+          this.searchTarget.value = opt.label
+          this.close()
+          this.inputTarget.dispatchEvent(new Event("change", { bubbles: true }))
+        }
+        break
+      case "Escape":
+        this.close()
+        break
+    }
+  }
+
+  renderDropdown() {
+    const opts = this.filteredOptions || this.parentFilteredOptions
+
+    // Clear existing content using safe DOM manipulation (avoids innerHTML XSS risk)
+    while (this.dropdownTarget.firstChild) {
+      this.dropdownTarget.removeChild(this.dropdownTarget.firstChild)
+    }
+
+    if (!opts.length) {
+      const empty = document.createElement("div")
+      empty.className = "px-3 py-2 text-sm text-slate-400"
+      empty.textContent = "No results found"
+      this.dropdownTarget.appendChild(empty)
+      return
+    }
+
+    opts.forEach((opt, index) => {
+      const btn = document.createElement("button")
+      btn.type = "button"
+      btn.className = [
+        "block w-full text-left px-3 py-2 text-sm hover:bg-slate-100",
+        index === this.selectedIndex ? "bg-slate-100" : "",
+        "text-slate-700",
+      ]
+        .filter(Boolean)
+        .join(" ")
+      btn.dataset.action =
+        "click->admin-suite--dependent-searchable-select#select"
+      btn.dataset.value = this.escapeAttr(String(opt.value))
+      btn.dataset.label = this.escapeAttr(String(opt.label))
+
+      // Label text node
+      btn.appendChild(document.createTextNode(opt.label))
+
+      // Optional group badge
+      if (opt.group) {
+        const badge = document.createElement("span")
+        badge.className =
+          "ml-2 text-xs text-slate-400 font-normal"
+        badge.textContent = opt.group
+        btn.appendChild(badge)
+      }
+
+      this.dropdownTarget.appendChild(btn)
+    })
+  }
+
+  // Escapes a string for use in HTML data attributes
+  escapeAttr(value) {
+    return String(value)
+      .replace(/&/g, "&amp;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+  }
+}

data/app/javascript/controllers/admin_suite/searchable_select_controller.js

@@ -195,6 +195,7 @@ export default class extends Controller {
     this.inputTarget.value = value
     this.searchTarget.value = label
     this.close()
+    this.inputTarget.dispatchEvent(new Event("change", { bubbles: true }))
   }
 
   async createOption(label) {

data/app/views/admin_suite/resources/index.html.erb

@@ -1,7 +1,7 @@
 <% content_for :title, "#{resource_config.human_name_plural} - Admin Suite" %>
 
 <%
-  has_new_route = begin
+  has_new_route = !resource_config.read_only? && begin
     url_for(action: :new)
     true
   rescue ActionController::UrlGenerationError
@@ -9,6 +9,8 @@
   end
 
   has_edit_route = ->(record) {
+    next false if resource_config.read_only?
+
     begin
       url_for(action: :edit, id: record.to_param)
       true

data/app/views/admin_suite/resources/show.html.erb

@@ -1,14 +1,14 @@
 <% content_for :title, "#{resource.respond_to?(:name) ? resource.name : "#{resource_config.human_name} ##{resource.id}"} - Admin Suite" %>
 
 <%
-  has_edit_route = begin
+  has_edit_route = !resource_config.read_only? && begin
     url_for(action: :edit, id: resource.to_param)
     true
   rescue ActionController::UrlGenerationError
     false
   end
 
-  has_destroy_route = begin
+  has_destroy_route = !resource_config.read_only? && begin
     url_for(action: :destroy, id: resource.to_param)
     true
   rescue ActionController::UrlGenerationError

data/app/views/layouts/admin_suite/application.html.erb

@@ -35,6 +35,7 @@
 
     <% if respond_to?(:javascript_importmap_tags) %>
       <%= javascript_importmap_tags %>
+      <%= javascript_import_module_tag "admin_suite_application" %>
     <% end %>
   </head>
 

data/config/importmap.rb

@@ -1 +1,2 @@
+pin "admin_suite_application", to: "admin_suite_application.js"
 pin_all_from File.expand_path("../app/javascript/controllers", __dir__), under: "controllers"

data/lib/admin/base/filter_builder.rb

@@ -57,7 +57,8 @@ module Admin
         # They are handled elsewhere (`apply_sort`) and must not be turned into SQL.
         return scope if %i[sort sort_direction direction page search].include?(filter.name.to_sym)
 
-        value = params[filter.name]
+        value = params[filter.name].presence
+        value = filter.default if value.blank? && filter.respond_to?(:default)
         return scope if value.blank?
 
         if filter.respond_to?(:apply) && filter.apply.present?

data/lib/admin/base/resource.rb

@@ -165,6 +165,17 @@ module Admin
           @export_formats = formats
         end
 
+        # Declares whether the generic resource routes may mutate records.
+        # Read-only resources retain index/show access while the controller
+        # rejects direct requests to every built-in mutation endpoint.
+        def read_only(value = true)
+          @read_only = value
+        end
+
+        def read_only?
+          @read_only == true
+        end
+
         # Returns the resource name derived from class name
         #
         # @return [String]
@@ -328,12 +339,13 @@ module Admin
             placeholder: options[:placeholder],
             options: select_options,
             field: options[:field] || name,
-            apply: options[:apply]
+            apply: options[:apply],
+            default: options[:default]
           )
         end
       end
 
-      FilterDefinition = Struct.new(:name, :type, :label, :placeholder, :options, :field, :apply, keyword_init: true)
+      FilterDefinition = Struct.new(:name, :type, :label, :placeholder, :options, :field, :apply, :default, keyword_init: true)
 
       class StatsBuilder
         attr_reader :stats
@@ -380,7 +392,8 @@ module Admin
             preview: options[:preview] != false,
             variants: options[:variants],
             label_color: options[:label_color],
-            label_size: options[:label_size]
+            label_size: options[:label_size],
+            parent_field: options[:parent_field]
           )
         end
 
@@ -406,7 +419,7 @@ module Admin
         :name, :type, :required, :label, :help, :placeholder,
         :collection, :create_url, :accept, :rows, :readonly,
         :if_condition, :unless_condition, :multiple, :creatable,
-        :preview, :variants, :label_color, :label_size,
+        :preview, :variants, :label_color, :label_size, :parent_field,
         keyword_init: true
       )
 

data/lib/admin_suite/ui/field_renderer_registry.rb

@@ -58,6 +58,10 @@ AdminSuite::UI::FieldRendererRegistry.register(:searchable_select) do |view, f,
   view.render_searchable_select(f, field, resource)
 end
 
+AdminSuite::UI::FieldRendererRegistry.register(:dependent_select) do |view, f, field, resource, _field_class|
+  view.render_dependent_searchable_select(f, field, resource)
+end
+
 AdminSuite::UI::FieldRendererRegistry.register(:multi_select) do |view, f, field, resource, _field_class|
   view.render_multi_select(f, field, resource)
 end

data/lib/admin_suite/version.rb

@@ -2,7 +2,7 @@
 
 module AdminSuite
   module Version
-    VERSION = "0.2.7"
+    VERSION = "0.2.9"
   end
 
   # Backward-compatible constant.