admin_suite 0.1.0

data/lib/admin_suite.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+begin
+  require "lucide-rails"
+rescue LoadError
+  # Host app may choose a different icon provider via `AdminSuite.config.icon_renderer`.
+end
+
+require "pagy"
+
+require "admin_suite/version"
+require "admin_suite/configuration"
+require "admin_suite/markdown_renderer"
+require "admin_suite/theme_palette"
+require "admin_suite/portal_registry"
+require "admin_suite/portal_definition"
+require "admin_suite/ui/form_field_renderer"
+require "admin_suite/ui/show_value_formatter"
+require "admin_suite/engine"
+
+module AdminSuite
+  class << self
+    # @return [AdminSuite::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # @yieldparam config [AdminSuite::Configuration]
+    # @return [AdminSuite::Configuration]
+    def configure
+      yield(config)
+      config
+    end
+
+    # Defines (or updates) a portal using a Ruby DSL.
+    #
+    # Host apps typically place these in `app/admin/portals/*.rb`.
+    #
+    # @param key [Symbol, String]
+    # @yield Portal definition DSL
+    # @return [AdminSuite::PortalDefinition]
+    def portal(key, &block)
+      definition = PortalDefinition.new(key)
+      definition.instance_eval(&block) if block_given?
+      PortalRegistry.register(definition)
+      definition
+    end
+
+    # @return [Hash{Symbol=>AdminSuite::PortalDefinition}]
+    def portal_definitions
+      PortalRegistry.all
+    end
+  end
+end

data/lib/generators/admin_suite/install/install_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module AdminSuite
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs AdminSuite initializer and mounts the engine."
+
+      class_option :mount_path, type: :string, default: "/internal/admin", desc: "Path to mount AdminSuite::Engine"
+
+      def create_initializer
+        template "admin_suite.rb", "config/initializers/admin_suite.rb"
+      end
+
+      def mount_engine
+        route %(mount AdminSuite::Engine => "#{options[:mount_path]}")
+      end
+    end
+  end
+end

data/lib/generators/admin_suite/install/templates/admin_suite.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# AdminSuite configuration (host app adapter layer).
+AdminSuite.configure do |config|
+  # Hook called as a before_action inside the engine.
+  # config.authenticate = ->(controller) { ... }
+  config.authenticate = nil
+
+  # Actor used for actions/auditing/authorization.
+  # config.current_actor = ->(controller) { ... }
+  config.current_actor = ->(controller) { controller.respond_to?(:current_user) ? controller.current_user : nil }
+
+  # Optional authorization hook (Pundit/CanCan/ActionPolicy/custom).
+  # config.authorize = ->(actor, action:, subject:, resource:, controller:) { true }
+  config.authorize = nil
+
+  # Resource definition file globs (host app can override).
+  config.resource_globs = [
+    Rails.root.join("config/admin_suite/resources/*.rb").to_s,
+    Rails.root.join("app/admin/resources/*.rb").to_s
+  ]
+
+  # Portal dashboard DSL globs (host app can override).
+  # Files typically call `AdminSuite.portal :ops do ... end`
+  config.portal_globs = [
+    Rails.root.join("config/admin_suite/portals/*.rb").to_s,
+    Rails.root.join("app/admin/portals/*.rb").to_s
+  ]
+
+  # Portal metadata (host app can override).
+  config.portals = {
+    ops: { label: "Ops Portal", icon: "settings", color: :amber, order: 10 }
+  }
+
+  # Theme (Tailwind color names).
+  config.theme = { primary: :indigo, secondary: :purple }
+
+  # Optional host stylesheet to include after AdminSuite's baseline CSS.
+  # In apps that use Tailwind, this is typically `:app`.
+  config.host_stylesheet = :app
+
+  # Tailwind CDN fallback (helps when host doesn't compile Tailwind).
+  # Disable if you provide your own Tailwind build.
+  config.tailwind_cdn = true
+
+  # Optional docs link shown in the sidebar.
+  # config.docs_url = "https://..."
+  config.docs_url = nil
+
+  # Docs viewer source folder (host app filesystem).
+  # Defaults to Rails.root/docs.
+  config.docs_path = Rails.root.join("docs")
+
+  # Partial overrides.
+  # config.partials[:flash] = "my/shared/flash"
+  # config.partials[:panel_stat] = "my/admin/panels/stat"
+
+  # Custom renderers:
+  # config.custom_renderers[:my_renderer] = ->(record, view_context) { ... }
+end

data/lib/generators/admin_suite/resource/resource_generator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module AdminSuite
+  module Generators
+    class ResourceGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :model_name, type: :string, required: true, desc: "ActiveRecord model name (e.g. User)"
+
+      class_option :portal, type: :string, default: "ops", desc: "Portal key (e.g. ops, ai, assistant)"
+      class_option :section, type: :string, default: "general", desc: "Sidebar section key"
+      class_option :output_dir, type: :string, default: "app/admin/resources", desc: "Where to write the resource file"
+
+      def create_resource_definition
+        @model_class_name = model_name.camelize
+        @resource_class_name = "#{@model_class_name}Resource"
+        @portal = options[:portal].to_s
+        @section = options[:section].to_s
+
+        klass = safe_constantize(@model_class_name)
+        @columns = build_columns(klass)
+        @searchable = build_searchable(klass)
+        @form_fields = build_form_fields(klass)
+
+        template "resource.rb.tt", File.join(options[:output_dir], "#{@model_class_name.underscore}_resource.rb")
+      end
+
+      private
+
+      def safe_constantize(name)
+        name.constantize
+      rescue NameError
+        nil
+      end
+
+      def build_columns(klass)
+        return [] unless klass&.respond_to?(:columns_hash)
+
+        keys = klass.columns_hash.keys
+        preferred = %w[id name title email email_address status active created_at updated_at]
+        chosen = (preferred & keys)
+        chosen = (chosen + (keys - chosen)).uniq
+        chosen.take(6).map(&:to_sym)
+      end
+
+      def build_searchable(klass)
+        return [] unless klass&.respond_to?(:columns_hash)
+
+        stringish = klass.columns.select { |c| %i[string text].include?(c.type) }.map(&:name)
+        preferred = %w[name title email email_address]
+        (preferred & stringish).presence || stringish.take(3)
+      end
+
+      def build_form_fields(klass)
+        return [] unless klass&.respond_to?(:columns)
+
+        enums = klass.respond_to?(:defined_enums) ? klass.defined_enums : {}
+
+        klass.columns.reject { |c| %w[id created_at updated_at].include?(c.name) }.map do |c|
+          name = c.name
+          if enums.key?(name)
+            { name: name, type: :select, enum: enums[name].keys }
+          else
+            type =
+              case c.type
+              when :boolean then :toggle
+              when :text then :textarea
+              when :json, :jsonb then :json
+              when :datetime, :timestamp then :datetime
+              when :date then :date
+              when :integer, :bigint, :float, :decimal then :number
+              else
+                :text
+              end
+            { name: name, type: type }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/admin_suite/resource/templates/resource.rb.tt

@@ -0,0 +1,47 @@
+<%# frozen_string_literal: true %>
+
+module Admin
+  module Resources
+    class <%= @resource_class_name %> < Admin::Base::Resource
+      model ::<%= @model_class_name %>
+      portal :<%= @portal %>
+      section :<%= @section %>
+
+      index do
+        <% if @searchable.present? %>
+        searchable <%= @searchable.map { |f| ":#{f}" }.join(", ") %>
+        <% end %>
+        sortable :created_at, default: :created_at, direction: :desc
+
+        columns do
+          <% @columns.each do |col| %>
+          column :<%= col %>
+          <% end %>
+        end
+      end
+
+      form do
+        <% @form_fields.each do |f| %>
+          <% if f[:type] == :select %>
+        field :<%= f[:name] %>, type: :select, collection: <%= f[:enum].map { |v| [v.humanize, v] }.inspect %>
+          <% elsif f[:type] == :textarea %>
+        field :<%= f[:name] %>, type: :textarea
+          <% elsif f[:type] == :toggle %>
+        field :<%= f[:name] %>, type: :toggle
+          <% elsif f[:type] == :json %>
+        field :<%= f[:name] %>, type: :json
+          <% elsif f[:type] == :datetime %>
+        field :<%= f[:name] %>, type: :datetime
+          <% elsif f[:type] == :date %>
+        field :<%= f[:name] %>, type: :date
+          <% elsif f[:type] == :number %>
+        field :<%= f[:name] %>, type: :number
+          <% else %>
+        field :<%= f[:name] %>
+          <% end %>
+        <% end %>
+      end
+    end
+  end
+end
+

data/lib/generators/admin_suite/scaffold/scaffold_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module AdminSuite
+  module Generators
+    class ScaffoldGenerator < Rails::Generators::Base
+      argument :model_name, type: :string, required: true
+      argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+      class_option :portal, type: :string, default: "ops"
+      class_option :section, type: :string, default: "general"
+
+      def run_rails_scaffold
+        Rails::Generators.invoke("scaffold", [ model_name, *attributes ], behavior: behavior)
+      end
+
+      def run_admin_suite_resource
+        Rails::Generators.invoke(
+          "admin_suite:resource",
+          [ model_name ],
+          portal: options[:portal],
+          section: options[:section]
+        )
+      end
+    end
+  end
+end

data/lib/tasks/admin_suite_tailwind.rake

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+namespace :admin_suite do
+  namespace :tailwind do
+    desc "Build AdminSuite Tailwind CSS into host app builds"
+    task build: :environment do
+      engine_root = AdminSuite::Engine.root
+      input = engine_root.join("app/assets/tailwind/admin_suite.css")
+      output = Rails.root.join("app/assets/builds/admin_suite_tailwind.css")
+
+      FileUtils.mkdir_p(output.dirname)
+
+      cmd = [
+        "tailwindcss",
+        "-i", input.to_s,
+        "-o", output.to_s,
+        "--minify"
+      ]
+
+      puts("[admin_suite] building Tailwind CSS -> #{output}")
+      success = system(*cmd)
+      raise("AdminSuite Tailwind build failed (#{cmd.join(' ')})") unless success
+    end
+  end
+end
+
+# Ensure the engine stylesheet is present for production builds.
+Rake::Task["assets:precompile"].enhance([ "admin_suite:tailwind:build" ]) if Rake::Task.task_defined?("assets:precompile")

data/lib/tasks/admin_suite_test.rake

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+namespace :admin_suite do
+  desc "Run AdminSuite gem tests (Minitest)"
+  Rake::TestTask.new(:test) do |t|
+    t.libs << "test"
+    t.pattern = "test/**/*_test.rb"
+  end
+end

data/test/dummy/Gemfile

@@ -0,0 +1,21 @@
+source "https://rubygems.org"
+
+# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
+gem "rails", "~> 8.1.2"
+# The modern asset pipeline for Rails [https://github.com/rails/propshaft]
+gem "propshaft"
+# Use sqlite3 as the database for Active Record
+gem "sqlite3", ">= 2.1"
+# Use the Puma web server [https://github.com/puma/puma]
+gem "puma", ">= 5.0"
+
+# Use the engine under test.
+gem "admin_suite", path: "../.."
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: %i[ windows jruby ]
+
+group :development, :test do
+  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
+  gem "debug", platforms: %i[ mri windows ], require: "debug/prelude"
+end

data/test/dummy/README.md

@@ -0,0 +1,24 @@
+# README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...

data/test/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/test/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,10 @@
+/*
+ * This is a manifest file that'll be compiled into application.css.
+ *
+ * With Propshaft, assets are served efficiently without preprocessing steps. You can still include
+ * application-wide styles in this file, but keep in mind that CSS precedence will follow the standard
+ * cascading order, meaning styles declared later in the document or manifest will override earlier ones,
+ * depending on specificity.
+ *
+ * Consider organizing styles into separate files for maintainability.
+ */

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,4 @@
+class ApplicationController < ActionController::Base
+  # Only allow modern browsers supporting webp images, web push, badges, import maps, CSS nesting, and CSS :has.
+  allow_browser versions: :modern
+end

data/test/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/test/dummy/app/models/application_record.rb

@@ -0,0 +1,2 @@
+class ApplicationRecord
+end

data/test/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= content_for(:title) || "Dummy" %></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="Dummy">
+    <meta name="mobile-web-app-capable" content="yes">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= yield :head %>
+
+    <%# Enable PWA manifest for installable apps (make sure to enable in config/routes.rb too!) %>
+    <%#= tag.link rel: "manifest", href: pwa_manifest_path(format: :json) %>
+
+    <link rel="icon" href="/icon.png" type="image/png">
+    <link rel="icon" href="/icon.svg" type="image/svg+xml">
+    <link rel="apple-touch-icon" href="/icon.png">
+
+    <%# Includes all stylesheet files in app/assets/stylesheets %>
+    <%= stylesheet_link_tag :app %>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/test/dummy/app/views/pwa/manifest.json.erb

@@ -0,0 +1,22 @@
+{
+  "name": "Dummy",
+  "icons": [
+    {
+      "src": "/icon.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    },
+    {
+      "src": "/icon.png",
+      "type": "image/png",
+      "sizes": "512x512",
+      "purpose": "maskable"
+    }
+  ],
+  "start_url": "/",
+  "display": "standalone",
+  "scope": "/",
+  "description": "Dummy.",
+  "theme_color": "red",
+  "background_color": "red"
+}

data/test/dummy/app/views/pwa/service-worker.js

@@ -0,0 +1,26 @@
+// Add a service worker for processing Web Push notifications:
+//
+// self.addEventListener("push", async (event) => {
+//   const { title, options } = await event.data.json()
+//   event.waitUntil(self.registration.showNotification(title, options))
+// })
+//
+// self.addEventListener("notificationclick", function(event) {
+//   event.notification.close()
+//   event.waitUntil(
+//     clients.matchAll({ type: "window" }).then((clientList) => {
+//       for (let i = 0; i < clientList.length; i++) {
+//         let client = clientList[i]
+//         let clientPath = (new URL(client.url)).pathname
+//
+//         if (clientPath == event.notification.data.path && "focus" in client) {
+//           return client.focus()
+//         }
+//       }
+//
+//       if (clients.openWindow) {
+//         return clients.openWindow(event.notification.data.path)
+//       }
+//     })
+//   )
+// })

data/test/dummy/bin/ci

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+require_relative "../config/boot"
+require "active_support/continuous_integration"
+
+CI = ActiveSupport::ContinuousIntegration
+require_relative "../config/ci.rb"

data/test/dummy/bin/dev

@@ -0,0 +1,2 @@
+#!/usr/bin/env ruby
+exec "./bin/rails", "server", *ARGV

data/test/dummy/bin/rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+APP_PATH = File.expand_path("../config/application", __dir__)
+require_relative "../config/boot"
+require "rails/commands"

data/test/dummy/bin/rake

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative "../config/boot"
+require "rake"
+Rake.application.run

data/test/dummy/bin/setup

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+require "fileutils"
+
+APP_ROOT = File.expand_path("..", __dir__)
+
+def system!(*args)
+  system(*args, exception: true)
+end
+
+FileUtils.chdir APP_ROOT do
+  # This script is a way to set up or update your development environment automatically.
+  # This script is idempotent, so that you can run it at any time and get an expectable outcome.
+  # Add necessary setup steps to this file.
+
+  puts "== Installing dependencies =="
+  system("bundle check") || system!("bundle install")
+
+  # puts "\n== Copying sample files =="
+  # unless File.exist?("config/database.yml")
+  #   FileUtils.cp "config/database.yml.sample", "config/database.yml"
+  # end
+
+  puts "\n== Preparing database =="
+  system! "bin/rails db:prepare"
+  system! "bin/rails db:reset" if ARGV.include?("--reset")
+
+  puts "\n== Removing old logs and tempfiles =="
+  system! "bin/rails log:clear tmp:clear"
+
+  unless ARGV.include?("--skip-server")
+    puts "\n== Starting development server =="
+    STDOUT.flush # flush the output before exec(2) so that it displays
+    exec "bin/dev"
+  end
+end

data/test/dummy/config/application.rb

@@ -0,0 +1,43 @@
+require_relative "boot"
+
+require "rails"
+# Pick the frameworks you want:
+require "active_model/railtie"
+require "active_job/railtie"
+# AdminSuite does not require a database; keep the dummy app DB-free.
+# require "active_record/railtie"
+# require "active_storage/engine"
+require "action_controller/railtie"
+# require "action_mailer/railtie"
+# require "action_mailbox/engine"
+# require "action_text/engine"
+require "action_view/railtie"
+# require "action_cable/engine"
+require "rails/test_unit/railtie"
+
+# Require the gems listed in Gemfile, including any gems
+# you've limited to :test, :development, or :production.
+Bundler.require(*Rails.groups)
+
+module Dummy
+  class Application < Rails::Application
+    # Initialize configuration defaults for originally generated Rails version.
+    config.load_defaults 8.1
+
+    # Please, add to the `ignore` list any other `lib` subdirectories that do
+    # not contain `.rb` files, or that should not be reloaded or eager loaded.
+    # Common ones are `templates`, `generators`, or `middleware`, for example.
+    config.autoload_lib(ignore: %w[assets tasks])
+
+    # Configuration for the application, engines, and railties goes here.
+    #
+    # These settings can be overridden in specific environments using the files
+    # in config/environments, which are processed later.
+    #
+    # config.time_zone = "Central Time (US & Canada)"
+    # config.eager_load_paths << Rails.root.join("extras")
+
+    # Don't generate system test files.
+    config.generators.system_tests = nil
+  end
+end

data/test/dummy/config/boot.rb

@@ -0,0 +1,3 @@
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "bundler/setup" # Set up gems listed in the Gemfile.

data/test/dummy/config/ci.rb

@@ -0,0 +1,19 @@
+# Run using bin/ci
+
+CI.run do
+  step "Setup", "bin/setup --skip-server"
+
+  step "Tests: Rails", "bin/rails test"
+  step "Tests: Seeds", "env RAILS_ENV=test bin/rails db:seed:replant"
+
+  # Optional: Run system tests
+  # step "Tests: System", "bin/rails test:system"
+
+  # Optional: set a green GitHub commit status to unblock PR merge.
+  # Requires the `gh` CLI and `gh extension install basecamp/gh-signoff`.
+  # if success?
+  #   step "Signoff: All systems go. Ready for merge and deploy.", "gh signoff"
+  # else
+  #   failure "Signoff: CI failed. Do not merge or deploy.", "Fix the issues and try again."
+  # end
+end

data/test/dummy/config/database.yml

@@ -0,0 +1,31 @@
+# SQLite. Versions 3.8.0 and up are supported.
+#   gem install sqlite3
+#
+#   Ensure the SQLite 3 gem is defined in your Gemfile
+#   gem "sqlite3"
+#
+default: &default
+  adapter: sqlite3
+  max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  timeout: 5000
+
+development:
+  <<: *default
+  database: storage/development.sqlite3
+
+# Warning: The database defined as "test" will be erased and
+# re-generated from your development database when you run "rake".
+# Do not set this db to the same as development or production.
+test:
+  <<: *default
+  database: storage/test.sqlite3
+
+# SQLite3 write its data on the local filesystem, as such it requires
+# persistent disks. If you are deploying to a managed service, you should
+# make sure it provides disk persistence, as many don't.
+#
+# Similarly, if you deploy your application as a Docker container, you must
+# ensure the database is located in a persisted volume.
+production:
+  <<: *default
+  # database: path/to/persistent/storage/production.sqlite3

data/test/dummy/config/environment.rb

@@ -0,0 +1,5 @@
+# Load the Rails application.
+require_relative "application"
+
+# Initialize the Rails application.
+Rails.application.initialize!