admin_suite 0.1.0

data/app/views/admin_suite/shared/_json_editor_field.html.erb

@@ -0,0 +1,52 @@
+<%# JSON Editor Field for Admin Suite Forms
+    Parameters:
+    - f: Form builder object (required)
+    - field: FieldDefinition object (required)
+    - resource: The resource being edited (required)
+-%>
+<%
+  value = resource.public_send(field.name)
+  rows = field.rows || 10
+  formatted_value = if value.is_a?(Hash) || value.is_a?(Array)
+    JSON.pretty_generate(value)
+  elsif value.present?
+    value.to_s
+  else
+    "{}"
+  end
+%>
+
+<div data-controller="admin-suite--json-editor">
+  <% if field.help.present? %>
+    <p class="text-sm text-slate-500 dark:text-slate-400 mb-2"><%= field.help %></p>
+  <% else %>
+    <p class="text-sm text-slate-500 dark:text-slate-400 mb-2">Enter valid JSON. Use the Format button to pretty-print.</p>
+  <% end %>
+
+  <div class="relative">
+    <%= f.text_area field.name,
+        rows: rows,
+        class: "form-input w-full font-mono text-sm",
+        value: formatted_value,
+        readonly: field.readonly,
+        data: {
+          "admin-suite--json-editor-target": "input",
+          action: "input->admin-suite--json-editor#validate"
+        } %>
+
+    <div class="absolute top-2 right-2">
+      <button
+        type="button"
+        data-action="click->admin-suite--json-editor#format"
+        class="px-3 py-1.5 text-xs font-medium text-slate-700 dark:text-slate-300 bg-slate-100 dark:bg-slate-700 hover:bg-slate-200 dark:hover:bg-slate-600 rounded transition-colors"
+      >
+        Format JSON
+      </button>
+    </div>
+  </div>
+
+  <div
+    data-admin-suite--json-editor-target="error"
+    class="hidden mt-2 text-sm text-red-600 dark:text-red-400"
+  ></div>
+</div>

data/app/views/admin_suite/shared/_sidebar.html.erb

@@ -0,0 +1,94 @@
+<%# Admin Suite Sidebar - mirrors internal/developer styling %>
+
+<% sorted_portals = navigation_items.sort_by { |(_key, meta)| (meta[:order] || 100).to_i } %>
+
+<aside class="admin-suite-sidebar flex flex-col w-72 h-full">
+  <!-- Header -->
+  <div class="flex items-center justify-between h-16 px-4 border-b border-white/10">
+    <%= link_to root_path, class: "flex items-center gap-3" do %>
+      <div class="flex items-center justify-center w-9 h-9 rounded-lg bg-white/10 border border-white/15">
+        <%= admin_suite_icon("code", class: "w-5 h-5 text-white") %>
+      </div>
+      <div>
+        <span class="text-lg font-bold text-white">Developer</span>
+        <span class="block text-xs text-white/80">Admin Suite</span>
+      </div>
+    <% end %>
+  </div>
+
+  <!-- Quick Links -->
+  <div class="px-3 py-3 border-b border-white/10">
+    <div class="flex gap-2">
+      <%= link_to root_path,
+          class: "flex-1 px-3 py-2 text-xs font-medium text-white bg-white/10 rounded-lg hover:bg-white/20 text-center transition-colors" do %>
+        Dashboard
+      <% end %>
+      <% docs = AdminSuite.config.docs_url %>
+      <% docs_url = docs.respond_to?(:call) ? docs.call(self) : docs %>
+      <% if docs_url.present? %>
+        <%= link_to docs_url,
+            class: "flex-1 px-3 py-2 text-xs font-medium text-white bg-white/10 rounded-lg hover:bg-white/20 text-center transition-colors",
+            target: "_blank",
+            rel: "noopener noreferrer" do %>
+          Docs
+        <% end %>
+      <% else %>
+        <%= link_to docs_path,
+            class: "flex-1 px-3 py-2 text-xs font-medium text-white bg-white/10 rounded-lg hover:bg-white/20 text-center transition-colors" do %>
+          Docs
+        <% end %>
+      <% end %>
+    </div>
+  </div>
+
+  <!-- Portal Navigation -->
+  <nav class="flex-1 overflow-y-auto px-3 py-4 space-y-2">
+    <% sorted_portals.each do |portal_key, portal| %>
+      <% portal_home = portal_path(portal: portal_key) %>
+      <% portal_prefix = File.join(request.script_name.to_s, portal_key.to_s) %>
+      <% active = request.path.start_with?(portal_prefix) %>
+      <% color = portal_color(portal_key) %>
+
+      <div>
+        <%= link_to (portal_home || root_path),
+            class: "flex items-center gap-3 px-3 py-2.5 rounded-lg transition-colors #{active ? "bg-white/20 text-white" : "text-white/90 hover:bg-white/10 hover:text-white"}" do %>
+          <div class="admin-suite-portal-accent admin-suite-portal-accent--<%= color %> admin-suite-portal-chip flex items-center justify-center w-8 h-8 rounded-lg <%= active ? "" : "bg-white/10" %>">
+            <%= portal_icon(portal_key, class: "admin-suite-portal-icon w-4 h-4") %>
+          </div>
+          <span class="font-medium"><%= portal[:label] %></span>
+        <% end %>
+
+        <% if active %>
+          <div class="mt-1 ml-11 space-y-0.5 text-sm">
+            <% portal[:sections].sort_by { |(_k, s)| s[:label].to_s }.each do |_section_key, section| %>
+              <div class="text-xs font-medium text-white/70 uppercase tracking-wider px-3 pt-2 pb-1">
+                <%= section[:label] %>
+              </div>
+              <% section[:items].sort_by { |it| [ (it[:order] || 100).to_i, it[:label].to_s ] }.each do |item| %>
+                <% item_active = request.path.start_with?(item[:path].to_s) %>
+                <%= link_to item[:path],
+                    class: "flex items-center gap-2 px-3 py-1.5 rounded #{item_active ? "text-white bg-white/20" : "text-white/90 hover:bg-white/10 hover:text-white"}",
+                    data: { turbo_frame: "_top" } do %>
+                  <% if item[:icon].present? %>
+                    <%= admin_suite_icon(item[:icon], class: "w-3.5 h-3.5 text-white/90") %>
+                  <% end %>
+                  <span class="truncate"><%= item[:label] %></span>
+                <% end %>
+              <% end %>
+            <% end %>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+  </nav>
+
+  <!-- Footer -->
+  <div class="p-3 border-t border-white/10">
+    <div class="px-3 py-2 text-xs text-white/70">
+      <div class="flex items-center justify-between">
+        <span>Admin Suite</span>
+        <span class="font-medium text-white/90"><%= sorted_portals.size %> Portals</span>
+      </div>
+    </div>
+  </div>
+</aside>

data/app/views/admin_suite/shared/_toggle_cell.html.erb

@@ -0,0 +1,34 @@
+<%# Toggle switch for boolean fields on index pages %>
+<%#
+  Required locals:
+    - record: The record to toggle
+    - field: The boolean field name (e.g., :value, :enabled, :active)
+    - toggle_url: (optional) Custom URL for the toggle action
+%>
+<%
+  value = record.public_send(field)
+  toggle_url ||= begin
+    url_for(action: :toggle, id: record.id, field: field)
+  rescue ActionController::UrlGenerationError
+    resource_toggle_path(portal: params[:portal], resource_name: params[:resource_name], id: record.id, field: field)
+  rescue StandardError
+    nil
+  end
+%>
+
+<%= turbo_frame_tag dom_id(record, :toggle), class: "admin-suite-toggle-wrap inline-flex align-middle" do %>
+  <% if toggle_url %>
+    <%= button_to toggle_url,
+        method: :post,
+        form: { data: { turbo_frame: dom_id(record, :toggle) }, class: "m-0 inline-flex align-middle items-center" },
+        class: "admin-suite-toggle-track #{value ? 'is-on' : ''}" do %>
+      <span class="sr-only">Toggle <%= field.to_s.humanize %></span>
+      <span class="admin-suite-toggle-thumb"></span>
+    <% end %>
+  <% else %>
+    <%# Read-only toggle display when no toggle URL available %>
+    <span class="admin-suite-toggle-track <%= value ? 'is-on' : '' %>">
+      <span class="admin-suite-toggle-thumb"></span>
+    </span>
+  <% end %>
+<% end %>

data/app/views/admin_suite/shared/_topbar.html.erb

@@ -0,0 +1,47 @@
+<%# Admin Suite Top Bar (mirrors internal/developer styling) %>
+
+<header class="bg-white border-b border-slate-200 h-16 flex-shrink-0">
+  <div class="flex items-center justify-between h-full px-4 sm:px-6">
+    <!-- Left side -->
+    <div class="flex items-center gap-4">
+      <!-- Mobile menu button -->
+      <button type="button"
+              class="lg:hidden p-2 rounded-lg text-slate-500 hover:bg-slate-100"
+              data-action="click->admin-suite--sidebar#toggle">
+        <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16"/>
+        </svg>
+      </button>
+
+      <!-- Breadcrumb / Current section -->
+      <div class="hidden sm:flex items-center gap-2 text-sm">
+        <span class="text-slate-400">Admin Suite</span>
+        <%= admin_suite_icon("chevron-right", class: "w-4 h-4 text-slate-300") %>
+        <span class="font-medium text-slate-900"><%= controller_name.humanize %></span>
+      </div>
+    </div>
+
+    <!-- Right side -->
+    <div class="flex items-center gap-3">
+      <!-- Environment Badge -->
+      <span class="hidden sm:inline-flex items-center px-2.5 py-1 rounded-full text-xs font-medium <%= theme_badge_primary_class %>">
+        <span class="admin-suite-env-dot w-1.5 h-1.5 rounded-full mr-1.5 animate-pulse"></span>
+        <%= Rails.env.to_s.humanize %>
+      </span>
+
+      <!-- Actor display -->
+      <div class="flex items-center gap-3 pl-3 border-l border-slate-200">
+        <div class="text-right hidden sm:block">
+          <% actor = admin_suite_actor %>
+          <p class="text-sm font-medium text-slate-900">
+            <%= actor&.respond_to?(:name) ? actor.name : actor&.respond_to?(:email) ? actor.email : actor&.respond_to?(:email_address) ? actor.email_address : "—" %>
+          </p>
+          <p class="text-xs text-slate-500">Actor</p>
+        </div>
+        <div class="admin-suite-avatar flex items-center justify-center w-9 h-9 rounded-full font-semibold text-sm">
+          <%= (admin_suite_actor&.respond_to?(:name) && admin_suite_actor.name.present?) ? admin_suite_actor.name.first.upcase : "A" %>
+        </div>
+      </div>
+    </div>
+  </div>
+</header>

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

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= content_for(:title) || "Admin Suite" %></title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <meta name="apple-mobile-web-app-capable" content="yes">
+    <meta name="application-name" content="Admin Suite">
+    <meta name="mobile-web-app-capable" content="yes">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= yield :head %>
+
+    <%# AdminSuite ships a baseline stylesheet so it can run without host Tailwind. %>
+    <%= stylesheet_link_tag "admin_suite", "data-turbo-track": "reload" %>
+
+    <%# Engine-build mode: AdminSuite ships its own compiled Tailwind CSS. %>
+    <%= stylesheet_link_tag "admin_suite_tailwind", "data-turbo-track": "reload" %>
+
+    <%# Scoped theme variables for AdminSuite (no host dependency). %>
+    <%= admin_suite_theme_style_tag %>
+
+    <%# Optional: allow host apps to include their own stylesheet after AdminSuite
+        (for brand tweaks/overrides). Not required for the engine to function. %>
+    <% host_stylesheet = AdminSuite.config.respond_to?(:host_stylesheet) ? AdminSuite.config.host_stylesheet : nil %>
+    <% if host_stylesheet.present? %>
+      <%= stylesheet_link_tag host_stylesheet, "data-turbo-track": "reload" %>
+    <% end %>
+
+    <%= stylesheet_link_tag "rouge", "data-turbo-track": "reload" %>
+
+    <%# EasyMDE Markdown Editor %>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/easymde@2.18.0/dist/easymde.min.css" data-turbo-track="reload">
+    <script src="https://cdn.jsdelivr.net/npm/easymde@2.18.0/dist/easymde.min.js" data-turbo-track="reload"></script>
+
+    <% if respond_to?(:javascript_importmap_tags) %>
+      <%= javascript_importmap_tags %>
+    <% end %>
+  </head>
+
+  <body class="admin-suite bg-slate-50">
+    <div class="flex h-screen overflow-hidden" data-controller="admin-suite--sidebar">
+      <!-- Sidebar -->
+      <div class="hidden lg:flex lg:flex-shrink-0">
+        <%= render "admin_suite/shared/sidebar" %>
+      </div>
+
+      <!-- Mobile sidebar overlay -->
+      <div data-admin-suite--sidebar-target="overlay"
+           class="hidden fixed inset-0 z-40 bg-slate-600 bg-opacity-75 lg:hidden"
+           data-action="click->admin-suite--sidebar#close">
+      </div>
+
+      <!-- Mobile sidebar -->
+      <div data-admin-suite--sidebar-target="mobileSidebar"
+           class="hidden fixed inset-y-0 left-0 z-50 w-72 transform transition-transform duration-300 ease-in-out lg:hidden">
+        <%= render "admin_suite/shared/sidebar" %>
+      </div>
+
+      <!-- Main content area -->
+      <div class="flex flex-col flex-1 overflow-hidden">
+        <!-- Top bar -->
+        <%= render "admin_suite/shared/topbar" %>
+
+        <!-- Main content -->
+        <main class="flex-1 overflow-y-auto bg-slate-50">
+          <!-- Flash messages -->
+          <% flash_partial = AdminSuite.config.partials[:flash].presence || "admin_suite/shared/flash" %>
+          <%= render flash_partial %>
+
+          <!-- Page content -->
+          <div class="py-6">
+            <%= yield %>
+          </div>
+        </main>
+      </div>
+    </div>
+  </body>
+</html>

data/lib/admin/base/action_executor.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Admin
+  module Base
+    class ActionExecutor
+      attr_reader :resource_class, :action_name, :actor
+
+      alias_method :current_user, :actor
+
+      Result = Struct.new(:success, :message, :redirect_url, :errors, keyword_init: true) do
+        def success? = success
+        def failure? = !success
+      end
+
+      def initialize(resource_class, action_name, actor)
+        @resource_class = resource_class
+        @action_name = action_name
+        @actor = actor
+      end
+
+      def execute_member(record, params = {})
+        action = find_member_action
+        return failure_result("Action not found") unless action
+        return failure_result("Condition not met") unless condition_met?(action, record)
+        execute_action(action, record, params)
+      end
+
+      def execute_bulk(records, params = {})
+        action = find_bulk_action
+        return failure_result("Action not found") unless action
+
+        results = records.map { |record| execute_action(action, record, params) }
+        success_count = results.count(&:success?)
+        failure_count = results.count(&:failure?)
+
+        if failure_count.zero?
+          success_result("Successfully processed #{success_count} records")
+        elsif success_count.zero?
+          failure_result("Failed to process all #{failure_count} records")
+        else
+          success_result("Processed #{success_count} records, #{failure_count} failed")
+        end
+      end
+
+      def execute_collection(scope, params = {})
+        action = find_collection_action
+        return failure_result("Action not found") unless action
+        execute_action(action, scope, params)
+      end
+
+      def action_definition
+        find_member_action || find_bulk_action || find_collection_action
+      end
+
+      private
+
+      def actions_config = @resource_class.actions_config
+
+      def find_member_action
+        return nil unless actions_config
+        actions_config.member_actions.find { |a| a.name == action_name }
+      end
+
+      def find_bulk_action
+        return nil unless actions_config
+        actions_config.bulk_actions.find { |a| a.name == action_name }
+      end
+
+      def find_collection_action
+        return nil unless actions_config
+        actions_config.collection_actions.find { |a| a.name == action_name }
+      end
+
+      def condition_met?(action, record)
+        return evaluate_condition(action.if_condition, record) if action.if_condition.present?
+        return !evaluate_condition(action.unless_condition, record) if action.unless_condition.present?
+        true
+      end
+
+      def evaluate_condition(condition_proc, record)
+        condition_proc.arity.zero? ? record.instance_exec(&condition_proc) : condition_proc.call(record)
+      end
+
+      def execute_action(action, target, params)
+        result =
+          if target.respond_to?(action.name)
+            execute_model_method(target, action)
+          elsif target.respond_to?("#{action.name}!")
+            execute_model_method(target, action, bang: true)
+          else
+            handler_class = find_handler_class(action)
+            handler_class ? execute_handler(handler_class, target, params) : failure_result("No handler found for action: #{action.name}")
+          end
+
+        notify_action_executed(action, target, params, result)
+        result
+      rescue StandardError => e
+        result = failure_result("Error: #{e.message}")
+        notify_action_executed(action, target, params, result)
+        result
+      end
+
+      def execute_model_method(record, action, bang: false)
+        method_name = bang ? "#{action.name}!" : action.name
+        record.public_send(method_name)
+        success_result("#{action.label} completed successfully")
+      rescue ActiveRecord::RecordInvalid => e
+        failure_result("Validation failed: #{e.record.errors.full_messages.join(', ')}")
+      rescue AASM::InvalidTransition => e
+        failure_result("Invalid state transition: #{e.message}")
+      end
+
+      def find_handler_class(action)
+        if defined?(AdminSuite) && AdminSuite.config.resolve_action_handler.present?
+          resolved = AdminSuite.config.resolve_action_handler.call(resource_class, action.name)
+          return resolved if resolved
+        end
+
+        handler_name = "#{resource_class.resource_name.camelize}#{action.name.to_s.camelize}Action"
+        "Admin::Actions::#{handler_name}".constantize
+      rescue NameError
+        nil
+      end
+
+      def execute_handler(handler_class, target, params)
+        handler_class.new(target, actor, params).call
+      end
+
+      def success_result(message, redirect_url: nil)
+        Result.new(success: true, message: message, redirect_url: redirect_url, errors: [])
+      end
+
+      def failure_result(message, errors: [])
+        Result.new(success: false, message: message, redirect_url: nil, errors: errors)
+      end
+
+      def notify_action_executed(action, target, params, result)
+        return unless defined?(AdminSuite)
+        hook = AdminSuite.config.on_action_executed
+        return unless hook
+
+        hook.call(
+          actor: actor,
+          action_name: action.name,
+          resource_class: resource_class,
+          subject: target,
+          params: params,
+          result: result
+        )
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/admin/base/action_handler.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Admin
+  module Base
+    class ActionHandler
+      attr_reader :record, :actor, :params
+
+      alias_method :current_user, :actor
+
+      def initialize(record, actor, params = {})
+        @record = record
+        @actor = actor
+        @params = params
+      end
+
+      def call
+        raise NotImplementedError, "Subclasses must implement #call"
+      end
+
+      protected
+
+      def success(message, redirect_url: nil)
+        Admin::Base::ActionExecutor::Result.new(success: true, message: message, redirect_url: redirect_url, errors: [])
+      end
+
+      def failure(message, errors: [])
+        Admin::Base::ActionExecutor::Result.new(success: false, message: message, redirect_url: nil, errors: errors)
+      end
+    end
+  end
+end

data/lib/admin/base/filter_builder.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Admin
+  module Base
+    class FilterBuilder
+      attr_reader :resource_class, :params
+
+      def initialize(resource_class, params)
+        @resource_class = resource_class
+        @params = params
+      end
+
+      def apply(scope)
+        scope = apply_search(scope)
+        scope = apply_filters(scope)
+        scope = apply_sort(scope)
+        scope
+      end
+
+      def filter_params
+        return {} unless index_config
+
+        permitted_keys = [ :search, :sort, :sort_direction, :page ]
+        permitted_keys += index_config.filters_list.map(&:name)
+
+        params.permit(*permitted_keys).to_h.symbolize_keys
+      end
+
+      private
+
+      def index_config
+        @resource_class.index_config
+      end
+
+      def apply_search(scope)
+        return scope unless index_config
+        return scope if params[:search].blank?
+        return scope if index_config.searchable_fields.empty?
+        return scope if params[:search].to_s.length < 3
+
+        search_term = "%#{params[:search]}%"
+        conditions = index_config.searchable_fields.map { |field| "#{field} ILIKE :search" }.join(" OR ")
+        scope.where(conditions, search: search_term)
+      end
+
+      def apply_filters(scope)
+        return scope unless index_config
+
+        index_config.filters_list.each do |filter|
+          scope = apply_filter(scope, filter)
+        end
+        scope
+      end
+
+      def apply_filter(scope, filter)
+        # Some "filters" in the UI are really just controls (e.g. sort dropdown).
+        # 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]
+        return scope if value.blank?
+
+        if filter.respond_to?(:apply) && filter.apply.present?
+          return apply_custom_filter(scope, filter.apply, value)
+        end
+
+        case filter.type
+        when :text, :search
+          scope.where("#{filter.field} ILIKE ?", "%#{value}%")
+        when :select
+          scope.where(filter.field => value)
+        when :toggle, :boolean
+          bool_value = ActiveModel::Type::Boolean.new.cast(value)
+          scope.where(filter.field => bool_value)
+        when :number
+          scope.where(filter.field => value.to_i)
+        when :date
+          date = Date.parse(value) rescue nil
+          return scope unless date
+          scope.where(filter.field => date.all_day)
+        when :date_range
+          from_date = params["#{filter.name}_from"].presence
+          to_date = params["#{filter.name}_to"].presence
+          scope = scope.where("#{filter.field} >= ?", Date.parse(from_date)) if from_date.present?
+          scope = scope.where("#{filter.field} <= ?", Date.parse(to_date).end_of_day) if to_date.present?
+          scope
+        when :association
+          scope.where("#{filter.field}_id" => value)
+        else
+          scope
+        end
+      end
+
+      def apply_custom_filter(scope, filter_proc, value)
+        filter_proc.arity == 2 ? filter_proc.call(scope, value) : filter_proc.call(scope, value, params)
+      end
+
+      def apply_sort(scope)
+        return scope unless index_config
+
+        sort_field = params[:sort].presence || index_config.default_sort
+        return scope unless sort_field
+
+        unless index_config.sortable_fields.include?(sort_field.to_sym)
+          sort_field = index_config.default_sort
+        end
+        return scope unless sort_field
+
+        direction_param = params[:sort_direction].presence || params[:direction].presence
+        direction =
+          if direction_param.present?
+            direction_param.to_sym == :desc ? :desc : :asc
+          else
+            (index_config.default_sort_direction || :desc).to_sym
+          end
+
+        scope.order(sort_field => direction)
+      end
+    end
+  end
+end