admin_suite 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 663de764696e7dc2696e54b4bb43381fe83ee33b74b9d212269ff6d25433466b
-  data.tar.gz: 9e9c6f145e86d4c8a0d1087cdc2d45c752da1fbbe9f1d4219d7b8874ebcc5291
+  metadata.gz: f50f5a24977b7bc8284ee051fb3d9d1746b49a1ab8d9ade00d917bf0a8ff412b
+  data.tar.gz: 6e32362f8fe763980b83fa34910b21020d7bdca7918afb5d63084aae7e80d72e
 SHA512:
-  metadata.gz: b23ab5d74fe3658980016cb8e7df4c1fe09a87601590b98b09dd43f3ece53c3d40f6cbc159aec035daec52525b8dbdbdf0da34ad8846061465ec9de05a270ae4
-  data.tar.gz: b70e3d18ec3aba0acd78fea6ee74efbec8201546253483abd00f1443e3411e37c9f98b065df6cf04f51ec3df28d9fa5e4ad90738781119f616c3c71db44f6130
+  metadata.gz: b980579e952dc4ec9cd1cd56dab61219f9320e810df0697a97ad42031e08fa59793c893adfdcd00e7d0ab7449468ae7d02a886f2dd6a3406c65bf5c750a28c3f
+  data.tar.gz: 603fdf2522093c9aba2427286e6573515a75d3016367dde07d3a74661bc7e15ffe95b1b388258c3398cc4d6583b85ef7c9ace18cc55e118b116344835802dfdc

data/CHANGELOG.md

@@ -7,6 +7,12 @@ 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
@@ -38,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/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/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

data/lib/admin_suite/version.rb

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

data/test/controllers/resources_controller_test.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module AdminSuite
+  class ResourcesControllerTest < ActiveSupport::TestCase
+    class TestController < ResourcesController
+      attr_writer :test_resource_config
+      attr_reader :filter_calls, :paginated_scope
+
+      def initialize
+        super
+        @filter_calls = 0
+      end
+
+      private
+
+      def resource_config
+        @test_resource_config
+      end
+
+      def filtered_collection
+        @filter_calls += 1
+        { total: 37 }
+      end
+
+      def paginate_collection(scope)
+        @paginated_scope = scope
+        [ Object.new, :paginated ]
+      end
+    end
+
+    class StatsResource < Admin::Base::Resource
+      index do
+        stats do
+          stat :legacy, -> { 11 }
+          stat :filtered, ->(scope) { scope.fetch(:total) }
+        end
+      end
+    end
+
+    class BrokenStatsResource < Admin::Base::Resource
+      index do
+        stats do
+          stat :broken, ->(_scope) { raise "boom" }
+        end
+      end
+    end
+
+    test "stats preserve zero arity calculators and pass the filtered scope to one arity calculators" do
+      controller = TestController.new
+      controller.test_resource_config = StatsResource
+      scope = { total: 37 }
+
+      stats = controller.send(:calculate_stats, scope)
+
+      assert_equal 11, stats.first[:value]
+      assert_equal 37, stats.second[:value]
+    end
+
+    test "stats preserve the existing calculator rescue behavior" do
+      controller = TestController.new
+      controller.test_resource_config = BrokenStatsResource
+
+      assert_equal "N/A", controller.send(:calculate_stats, Object.new).first[:value]
+    end
+
+    test "index reuses one filtered unpaginated scope for stats and pagination" do
+      controller = TestController.new
+      controller.test_resource_config = StatsResource
+
+      controller.index
+
+      assert_equal 1, controller.filter_calls
+      assert_equal({ total: 37 }, controller.paginated_scope)
+      assert_equal 37, controller.instance_variable_get(:@stats).second[:value]
+      assert_equal :paginated, controller.instance_variable_get(:@collection)
+    end
+  end
+end

data/test/integration/read_only_resource_test.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# The dummy app is intentionally database-free, while the generic controller
+# supports Active Record hosts. Supply only the exception type its lookup path
+# rescues so show-page behavior can be exercised with an in-memory fixture.
+unless defined?(ActiveRecord::RecordNotFound)
+  module ActiveRecord
+    class RecordNotFound < StandardError; end
+  end
+end
+
+module TurboFrameTestHelper
+  def turbo_frame_tag(name, **options, &block)
+    content_tag(:turbo_frame, capture(&block), id: name, **options)
+  end
+end
+
+ActionView::Base.include(TurboFrameTestHelper)
+
+module ReadOnlyResourceFixtures
+  class Relation
+    include Enumerable
+
+    def initialize(records)
+      @records = records
+    end
+
+    def each(&block)
+      @records.each(&block)
+    end
+
+    def count(*)
+      @records.count
+    end
+
+    def offset(*)
+      self
+    end
+
+    def limit(*)
+      self
+    end
+  end
+
+  class Widget
+    extend ActiveModel::Naming
+
+    attr_reader :id, :name
+
+    def initialize(id: 1, name: "Observed widget")
+      @id = id
+      @name = name
+    end
+
+    def self.all
+      Relation.new([ new ])
+    end
+
+    def self.column_names
+      %w[id name]
+    end
+
+    def self.primary_key
+      "id"
+    end
+
+    def self.columns_hash
+      { "id" => Struct.new(:type).new(:integer) }
+    end
+
+    def self.find(id)
+      raise ActiveRecord::RecordNotFound unless id.to_s == "1"
+
+      new
+    end
+
+    def to_param
+      id.to_s
+    end
+
+    def attributes
+      { "id" => id, "name" => name }
+    end
+  end
+end
+
+module Admin
+  module Resources
+    class ReadOnlyWidgetResource < Admin::Base::Resource
+      model ReadOnlyResourceFixtures::Widget
+      portal :ops
+      section :observability
+      read_only
+
+      index do
+        columns do
+          column :name
+        end
+      end
+    end
+  end
+end
+
+module AdminSuite
+  class ReadOnlyResourceTest < ActionDispatch::IntegrationTest
+    BASE_PATH = "/internal/admin_suite/ops/read_only_widgets"
+
+    test "direct built in mutation endpoints are rejected" do
+      get "#{BASE_PATH}/new"
+      assert_response :not_found
+
+      post BASE_PATH, params: { read_only_resource_fixtures_widget: { name: "changed" } }
+      assert_response :not_found
+
+      get "#{BASE_PATH}/1/edit"
+      assert_response :not_found
+
+      patch "#{BASE_PATH}/1", params: { read_only_resource_fixtures_widget: { name: "changed" } }
+      assert_response :not_found
+
+      delete "#{BASE_PATH}/1"
+      assert_response :not_found
+    end
+
+    test "index hides create and edit controls" do
+      get BASE_PATH
+
+      assert_response :success
+      assert_includes response.body, "Observed widget"
+      refute_includes response.body, "New Widget"
+      refute_match(/>\s*Edit\s*</, response.body)
+    end
+
+    test "show mutation controls are conditional on write access" do
+      template = AdminSuite::Engine.root.join("app/views/admin_suite/resources/show.html.erb").read
+
+      assert_includes template, "has_edit_route = !resource_config.read_only?"
+      assert_includes template, "has_destroy_route = !resource_config.read_only?"
+    end
+  end
+end

data/test/lib/resource_observability_extensions_test.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module AdminSuite
+  class ResourceObservabilityExtensionsTest < ActiveSupport::TestCase
+    FakeScope = Struct.new(:filters) do
+      def where(*arguments)
+        self.class.new(filters + [ arguments ])
+      end
+    end
+
+    class FilteredResource < Admin::Base::Resource
+      index do
+        filters do
+          filter :window, type: :select, default: "24h",
+            apply: ->(scope, value) { scope.where(window: value) }
+          filter :status, type: :select
+        end
+      end
+    end
+
+    class ReadOnlyResource < Admin::Base::Resource
+      read_only
+    end
+
+    test "resources are writable by default and may be declared read only" do
+      refute Admin::Base::Resource.read_only?
+      assert ReadOnlyResource.read_only?
+    end
+
+    test "filter defaults apply when the parameter is absent" do
+      scope = Admin::Base::FilterBuilder.new(FilteredResource, ActionController::Parameters.new)
+        .apply(FakeScope.new([]))
+
+      assert_equal [ [ { window: "24h" } ] ], scope.filters
+    end
+
+    test "filter defaults apply when the parameter is blank and compose with explicit filters" do
+      params = ActionController::Parameters.new(window: "", status: "failed")
+      scope = Admin::Base::FilterBuilder.new(FilteredResource, params).apply(FakeScope.new([]))
+
+      assert_equal [ [ { window: "24h" } ], [ { status: "failed" } ] ], scope.filters
+    end
+
+    test "an explicit filter overrides its default" do
+      params = ActionController::Parameters.new(window: "7d")
+      scope = Admin::Base::FilterBuilder.new(FilteredResource, params).apply(FakeScope.new([]))
+
+      assert_equal [ [ { window: "7d" } ] ], scope.filters
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: admin_suite
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.2.9
 platform: ruby
 authors:
 - TechWright Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -173,18 +173,6 @@ files:
 - app/views/layouts/admin_suite/application.html.erb
 - config/importmap.rb
 - config/routes.rb
-- docs/README.md
-- docs/actions.md
-- docs/configuration.md
-- docs/development.md
-- docs/docs_viewer.md
-- docs/fields.md
-- docs/installation.md
-- docs/portals.md
-- docs/releasing.md
-- docs/resources.md
-- docs/theming.md
-- docs/troubleshooting.md
 - lib/admin/base/action_executor.rb
 - lib/admin/base/action_handler.rb
 - lib/admin/base/filter_builder.rb
@@ -209,6 +197,7 @@ files:
 - lib/generators/admin_suite/scaffold/scaffold_generator.rb
 - lib/tasks/admin_suite_tailwind.rake
 - lib/tasks/admin_suite_test.rake
+- test/controllers/resources_controller_test.rb
 - test/dummy/Gemfile
 - test/dummy/README.md
 - test/dummy/Rakefile
@@ -253,9 +242,11 @@ files:
 - test/fixtures/docs/progress/PROGRESS_REPORT.md
 - test/integration/dashboard_test.rb
 - test/integration/docs_test.rb
+- test/integration/read_only_resource_test.rb
 - test/integration/theme_test.rb
 - test/lib/action_executor_test.rb
 - test/lib/markdown_renderer_test.rb
+- test/lib/resource_observability_extensions_test.rb
 - test/lib/theme_palette_test.rb
 - test/lib/zeitwerk_integration_test.rb
 - test/test_helper.rb

data/docs/README.md

@@ -1,26 +0,0 @@
-# AdminSuite Documentation
-
-AdminSuite is a mountable Rails engine that provides:
-
-- A **resource DSL** for CRUD + search/sort/filter + show/form configuration
-- A **portal system** (navigation + optional portal dashboards)
-- A built-in **docs viewer** (renders Markdown from your host app filesystem)
-- A small baseline **UI layer** (Tailwind optional)
-
-## Getting started
-
-- [Installation](installation.md)
-- [Configuration](configuration.md)
-- [Portals & dashboards](portals.md)
-- [Resources](resources.md)
-- [Fields](fields.md)
-- [Actions](actions.md)
-- [Theming & assets](theming.md)
-- [Docs viewer](docs_viewer.md)
-- [Troubleshooting](troubleshooting.md)
-
-## Contributing / maintainers
-
-- [Development](development.md)
-- [Releasing](releasing.md)
-