admin_suite 0.2.8 → 0.2.9

data/docs/actions.md

@@ -1,98 +0,0 @@
-# Actions
-
-AdminSuite supports three action “shapes” in the resource DSL:
-
-- `action` (member action on a single record)
-- `bulk_action` (runs across selected records)
-- `collection_action` (runs on a scope / collection)
-
-## Defining actions
-
-```ruby
-actions do
-  action :reindex, label: "Reindex", method: :post, confirm: "Reindex this record?"
-  bulk_action :archive, label: "Archive", confirm: "Archive selected records?"
-end
-```
-
-Supported action options:
-
-- `method:` HTTP method (default `:post`)
-- `label:` button label (default is humanized action name)
-- `icon:` lucide icon name (optional)
-- `color:` (optional)
-- `confirm:` string confirmation (optional)
-- `type:` reserved (default `:button`)
-- `if:` Proc condition (member actions only)
-- `unless:` Proc condition (member actions only)
-
-## How actions execute
-
-When you trigger an action, AdminSuite resolves behavior in this order:
-
-1. **Model method**: if the target responds to `action_name`, it calls that method.
-2. **Bang model method**: else if it responds to `action_name!`, it calls that.
-3. **Action handler class**: else it tries to find a handler class.
-
-### Handler class naming convention
-
-By default, AdminSuite looks for:
-
-```ruby
-Admin::Actions::<ResourceName><ActionName>Action
-```
-
-Example for `UserResource` + `:reset_password`:
-
-```ruby
-Admin::Actions::UserResetPasswordAction
-```
-
-Handlers should inherit from `Admin::Base::ActionHandler`:
-
-```ruby
-# app/admin/actions/user_reset_password_action.rb
-module Admin
-  module Actions
-    class UserResetPasswordAction < Admin::Base::ActionHandler
-      def call
-        # record is available as `record`, actor as `actor`, request params as `params`
-        record.send_reset_password_instructions!
-        success "Reset email sent."
-      rescue StandardError => e
-        failure "Failed to send reset: #{e.message}"
-      end
-    end
-  end
-end
-```
-
-## Overriding handler resolution (`config.resolve_action_handler`)
-
-If your app doesn’t want to follow the default naming convention, you can provide a resolver:
-
-```ruby
-AdminSuite.configure do |config|
-  config.resolve_action_handler = ->(resource_class, action_name) do
-    # return a Class or nil
-    if resource_class.name == "Admin::Resources::UserResource" && action_name.to_sym == :reset_password
-      Admin::Actions::UserResetPasswordAction
-    end
-  end
-end
-```
-
-## Auditing hook (`config.on_action_executed`)
-
-You can record or log all actions after they run:
-
-```ruby
-AdminSuite.configure do |config|
-  config.on_action_executed = ->(actor:, action_name:, resource_class:, subject:, params:, result:) do
-    Rails.logger.info(
-      "[admin_suite] actor=#{actor&.id} action=#{resource_class.name}##{action_name} success=#{result.success?}"
-    )
-  end
-end
-```
-

data/docs/configuration.md

@@ -1,284 +0,0 @@
-# Configuration
-
-AdminSuite is configured via an initializer:
-
-- `config/initializers/admin_suite.rb` (generated by `bin/rails g admin_suite:install`)
-
-All configuration lives on `AdminSuite.config` (an `AdminSuite::Configuration` instance).
-
-## Minimal secure configuration
-
-```ruby
-# config/initializers/admin_suite.rb
-AdminSuite.configure do |config|
-  config.authenticate = ->(controller) do
-    # Example: require an admin user
-    controller.redirect_to(controller.main_app.root_path) unless controller.respond_to?(:current_user) && controller.current_user&.admin?
-  end
-
-  config.current_actor = ->(controller) do
-    controller.respond_to?(:current_user) ? controller.current_user : nil
-  end
-end
-```
-
-## Defaults
-
-These are the defaults in `AdminSuite::Configuration` / `AdminSuite::Engine`:
-
-- `authenticate`: `nil`
-- `current_actor`: `nil`
-- `authorize`: `nil`
-- `logout_path`: `nil`
-- `logout_method`: `:delete`
-- `logout_label`: `"Log out"`
-- `resource_globs`: defaults to:
-  - `Rails.root/config/admin_suite/resources/*.rb`
-  - `Rails.root/app/admin/resources/*.rb`
-- `action_globs`: defaults to:
-  - `Rails.root/config/admin_suite/actions/*.rb`
-  - `Rails.root/app/admin/actions/*.rb`
-- `portal_globs`: defaults to:
-  - `Rails.root/config/admin_suite/portals/*.rb`
-  - `Rails.root/app/admin/portals/*.rb`
-  - `Rails.root/app/admin_suite/portals/*.rb`
-- `dashboard_globs`: defaults to:
-  - `Rails.root/config/admin_suite/dashboard.rb`
-  - `Rails.root/config/admin_suite/dashboard/*.rb`
-  - `Rails.root/app/admin_suite/dashboard.rb`
-  - `Rails.root/app/admin_suite/dashboard/*.rb`
-
-Note: AdminSuite definition files (resources, actions, portals) often don't follow 
-Zeitwerk's path-to-constant naming conventions. To prevent eager-load `Zeitwerk::NameError`s 
-in production, the engine only configures Zeitwerk to ignore these directories and load them via globs instead:
-- `app/admin_suite`
-- `app/admin/portals` (when portal DSL usage is detected)
-
-Other `app/admin/*` directories (such as `app/admin/resources`, `app/admin/actions`, and `app/admin/base`) are
-not ignored by default and may be treated as normal Zeitwerk autoload paths if they are added to the loader
-(for example, via `loader.push_dir("app/admin")` in the host app). Do not rely on these directories being
-ignored for autoloading; instead, keep files there Zeitwerk-compatible.
-
-We recommend placing non-Zeitwerk-compatible definition files under `config/admin_suite/*` or `app/admin_suite/*` 
-for clearer separation from standard Rails autoloading.
-- `portals`: default portal metadata for `:ops`, `:email`, `:ai`, `:assistant`
-- `custom_renderers`: `{}`
-- `icon_renderer`: `nil` (uses lucide-rails by default when available)
-- `docs_url`: `nil`
-- `docs_path`: `Rails.root.join("docs")`
-- `partials`: `{}`
-- `theme`: `{ primary: :indigo, secondary: :purple }`
-- `host_stylesheet`: `nil`
-- `tailwind_cdn`: `true`
-- `on_action_executed`: `nil`
-- `resolve_action_handler`: `nil`
-
-## Options
-
-### `authenticate`
-
-Called as a `before_action` inside the engine.
-
-- **Type**: `Proc` or `nil`
-- **Signature**: `->(controller) { ... }`
-
-If you don’t set it, AdminSuite will be accessible to any user that can reach the mounted route.
-
-### `current_actor`
-
-Used by actions/auditing hooks to identify “who initiated this”.
-
-- **Type**: `Proc` or `nil`
-- **Signature**: `->(controller) { current_user }`
-
-### `authorize`
-
-Optional authorization hook (you can wire Pundit/CanCan/ActionPolicy/etc).
-
-- **Type**: `Proc` or `nil`
-- **Signature**: `->(actor, action:, subject:, resource:, controller:) { true/false }`
-
-Note: this hook is available, but your app must call it from resource definitions / custom actions as needed (AdminSuite will not guess your authorization policy).
-
-### `logout_path`
-
-Optional sign-out action shown in the top bar.
-
-- **Type**: `Proc`, `String`, `Symbol`, or `nil`
-- **Proc signature**: `->(view_context) { ... }`
-
-Example:
-
-```ruby
-config.logout_path = ->(view) { view.main_app.internal_developer_logout_path }
-```
-
-### `logout_method`
-
-HTTP method for the topbar sign-out button.
-
-- **Type**: `Symbol` or `String`
-- **Default**: `:delete`
-
-### `logout_label`
-
-Button label for the topbar sign-out action.
-
-- **Type**: `String` (or `Proc` for dynamic label)
-- **Default**: `"Log out"`
-
-### `resource_globs`
-
-Where AdminSuite should load resource definition files from.
-
-- **Type**: `Array<String>`
-
-Example:
-
-```ruby
-config.resource_globs = [
-  Rails.root.join("app/admin/resources/**/*.rb").to_s
-]
-```
-
-### `action_globs`
-
-Where AdminSuite should load action handler files from (files that define custom action handlers, typically subclasses of `Admin::Base::ActionHandler`).
-
-- **Type**: `Array<String>`
-
-Example:
-
-```ruby
-config.action_globs = [
-  Rails.root.join("app/admin/actions/**/*.rb").to_s
-]
-```
-
-### `portal_globs`
-
-Where AdminSuite should load portal definition files from (files typically call `AdminSuite.portal(:key) { ... }`).
-
-- **Type**: `Array<String>`
-
-### `dashboard_globs`
-
-Where AdminSuite should load the root dashboard definition file(s) from (files typically call `AdminSuite.root_dashboard { ... }`).
-
-- **Type**: `Array<String>`
-
-### `root_dashboard_title`
-
-Optional title shown on the root dashboard.
-
-- **Type**: `String`, `Proc`, or `nil`
-- **Proc signature**: `->(controller) { "Admin Suite" }`
-
-### `root_dashboard_description`
-
-Optional description shown on the root dashboard.
-
-- **Type**: `String`, `Proc`, or `nil`
-- **Proc signature**: `->(controller) { "..." }`
-
-### `portals`
-
-Portal metadata used for navigation (label/icon/color/order). This is separate from the portal DSL and can be used alone.
-
-- **Type**: `Hash{Symbol => Hash}`
-
-Example:
-
-```ruby
-config.portals = {
-  ops: { label: "Ops", icon: "settings", color: :amber, order: 10 },
-  billing: { label: "Billing", icon: "credit-card", color: :emerald, order: 20 }
-}
-```
-
-### `theme`
-
-Two-color theme used to set CSS variables scoped to AdminSuite.
-
-- **Type**: `Hash` with `:primary` and `:secondary`
-- **Values**: Tailwind-ish color names (`:indigo`, `:emerald`, …) or a hex string (`"#4f46e5"`)
-
-See [Theming & assets](theming.md).
-
-### `host_stylesheet`
-
-If set, AdminSuite will include your host app stylesheet **after** its own styles in the engine layout.
-
-- **Type**: `Symbol` or `String` (passed to `stylesheet_link_tag`)
-- **Example**: `config.host_stylesheet = :app`
-
-### `tailwind_cdn`
-
-Reserved for host setups that want a CDN fallback. (AdminSuite already builds its own Tailwind CSS into your host app during `assets:precompile`.)
-
-- **Type**: `true/false`
-
-### `docs_url`
-
-If set, shows a “Docs” link in the AdminSuite sidebar.
-
-- **Type**: `String` or `nil`
-
-### `docs_path`
-
-Filesystem path where the docs viewer reads markdown from.
-
-- **Type**: `Pathname`, `String`, or `Proc`
-- **Proc signature**: `->(controller) { Rails.root.join("docs") }`
-
-### `partials`
-
-Override specific engine partials.
-
-- **Type**: `Hash`
-
-Example:
-
-```ruby
-config.partials[:flash] = "shared/flash"
-config.partials[:panel_stat] = "admin/panels/stat"
-```
-
-### `custom_renderers`
-
-Register custom show-section renderers (used when a show panel uses `render: :your_key`).
-
-- **Type**: `Hash{Symbol => Proc}`
-- **Proc signature**: `->(record, view_context) { ... }`
-
-Example:
-
-```ruby
-config.custom_renderers[:billing_snapshot] = ->(record, view) do
-  view.render(partial: "admin/billing_snapshot", locals: { record: record })
-end
-```
-
-### `icon_renderer`
-
-Replace the default icon provider (lucide-rails).
-
-- **Type**: `Proc` or `nil`
-- **Proc signature**: `->(name, view_context, **opts) { ... }`
-
-### `resolve_action_handler`
-
-Override how AdminSuite finds action handler classes.
-
-- **Type**: `Proc` or `nil`
-- **Proc signature**: `->(resource_class, action_name) { handler_class_or_nil }`
-
-See [Actions](actions.md).
-
-### `on_action_executed`
-
-Hook called after action execution (success or failure).
-
-- **Type**: `Proc` or `nil`
-- **Proc signature**: `->(actor:, action_name:, resource_class:, subject:, params:, result:) { ... }`
-

data/docs/development.md

@@ -1,64 +0,0 @@
-# Development
-
-This page is intended for contributors/maintainers working on the engine itself.
-
-## Setup
-
-From the gem root:
-
-```bash
-bundle install
-```
-
-## Run tests
-
-```bash
-bundle exec rake test
-```
-
-## Dummy app
-
-AdminSuite uses a Rails “dummy” app under `test/dummy` for integration tests and to
-exercise routing/assets in a host-like environment.
-
-Useful commands (from the gem root):
-
-```bash
-cd test/dummy
-bin/rails s
-```
-
-## Assets / Tailwind
-
-AdminSuite ships:
-
-- `app/assets/admin_suite.css` (baseline CSS)
-- `app/assets/tailwind/admin_suite.css` (Tailwind input)
-
-The engine Tailwind build task writes the compiled CSS into the **host app** builds folder:
-
-- Output: `Rails.root/app/assets/builds/admin_suite_tailwind.css`
-
-In a host app, this is run automatically during `assets:precompile`:
-
-```bash
-bin/rails admin_suite:tailwind:build
-```
-
-When developing inside the engine repo itself, you can run it from the dummy app:
-
-```bash
-cd test/dummy
-bin/rails admin_suite:tailwind:build
-```
-
-## Docs
-
-Engine docs live under:
-
-- `docs/`
-
-The docs viewer feature in the engine reads from the host app by default:
-
-- `Rails.root/docs` (configurable via `AdminSuite.config.docs_path`)
-

data/docs/docs_viewer.md

@@ -1,79 +0,0 @@
-# Docs viewer
-
-AdminSuite includes a built-in docs viewer at:
-
-- `/docs` (relative to the mount path)
-
-It renders Markdown (`.md`) files from a folder on your host app filesystem.
-
-## Quick start
-
-1. Create `docs/` in your host app:
-
-```bash
-mkdir -p docs
-```
-
-2. Add a markdown file:
-
-```md
-<!-- docs/getting_started.md -->
-# Getting started
-
-Hello from AdminSuite docs.
-```
-
-3. Visit:
-
-- `/internal/admin/docs`
-
-## Configuring the docs root (`config.docs_path`)
-
-By default:
-
-- `AdminSuite.config.docs_path = Rails.root.join("docs")`
-
-You can point it somewhere else:
-
-```ruby
-AdminSuite.configure do |config|
-  config.docs_path = Rails.root.join("admin_docs")
-end
-```
-
-Or compute per-request:
-
-```ruby
-AdminSuite.configure do |config|
-  config.docs_path = ->(_controller) { Rails.root.join("docs") }
-end
-```
-
-## Sidebar “Docs” link (`config.docs_url`)
-
-If you want a persistent docs link in the AdminSuite sidebar, set:
-
-```ruby
-AdminSuite.configure do |config|
-  config.docs_url = "/internal/admin/docs"
-end
-```
-
-This can also point to external docs.
-
-## Organization
-
-Docs are grouped by their first folder name. For example:
-
-- `docs/ops/runbooks.md` → group “Ops”
-- `docs/api/authentication.md` → group “API”
-- `docs/getting_started.md` → group “Docs”
-
-## Security notes
-
-The docs viewer defends against path traversal:
-
-- Rejects any path containing `..`
-- Requires a `.md` extension
-- Resolves realpaths and ensures the requested file stays under the docs root
-

data/docs/fields.md

@@ -1,188 +0,0 @@
-# Fields
-
-Fields are defined in the resource `form do ... end` block:
-
-```ruby
-form do
-  field :name
-  field :status, type: :select, collection: [["Active", "active"], ["Inactive", "inactive"]]
-end
-```
-
-## Common options
-
-All fields support:
-
-- `type:` (defaults to `:text`)
-- `required:` (`true/false`)
-- `label:` (String)
-- `help:` (String)
-- `placeholder:` (String)
-- `readonly:` (`true/false`)
-- `if:` Proc (render only if truthy)
-- `unless:` Proc (render only if falsy)
-
-Example conditional field:
-
-```ruby
-field :admin_notes, type: :textarea, if: ->(record) { record.admin? }
-```
-
-## Supported field types
-
-### Text-like
-
-- `:text` (default)
-- `:textarea` (`rows:` supported)
-- `:email`
-- `:url`
-- `:number`
-- `:date`
-- `:time`
-- `:datetime`
-
-### Toggle
-
-- `:toggle` (renders a switch)
-
-```ruby
-field :enabled, type: :toggle
-```
-
-### Select
-
-- `:select` (uses Rails `select`)
-
-Options:
-
-- `collection:` Array of `[label, value]` or simple values
-
-```ruby
-field :status, type: :select, collection: [["Active", "active"], ["Inactive", "inactive"]]
-```
-
-### Searchable select
-
-- `:searchable_select` (Stimulus-powered searchable dropdown)
-
-Options:
-
-- `collection:` either:
-  - an Array (static options), or
-  - a String URL (advanced; used by the JS controller as a “search URL”)
-- `create_url:` (String) enables “creatable” behavior in the UI
-
-```ruby
-field :company_id,
-  type: :searchable_select,
-  collection: Company.order(:name).pluck(:name, :id),
-  placeholder: "Search companies..."
-```
-
-### Multi-select & tags
-
-- `:multi_select`
-- `:tags`
-
-Options:
-
-- `collection:` Array of options (used for suggestions)
-- `create_url:` enables “creatable” behavior
-- `multiple:` boolean (reserved; arrays are permitted automatically)
-
-Notes:
-
-- These submit arrays and are permitted automatically by AdminSuite.
-- For `:tags`, AdminSuite uses a `tag_list` parameter by default (or `#{field_name}_list` if your model exposes it).
-
-```ruby
-field :tag_list, type: :tags, placeholder: "Add tags..."
-field :roles, type: :multi_select, collection: %w[admin editor viewer]
-```
-
-### File uploads / attachments
-
-- `:file`
-- `:attachment`
-- `:image`
-
-Options:
-
-- `accept:` MIME accept string (e.g. `"image/*"`, `"application/pdf"`)
-
-These assume your host app uses **Active Storage**.
-
-```ruby
-field :avatar, type: :image, accept: "image/*"
-field :resume, type: :file, accept: "application/pdf"
-```
-
-### Rich text
-
-- `:trix`
-- `:rich_text`
-
-These assume your host app uses **Action Text**.
-
-```ruby
-field :bio, type: :rich_text
-```
-
-### Markdown
-
-- `:markdown` (textarea enhanced by EasyMDE via CDN in the engine layout)
-
-```ruby
-field :prompt_template, type: :markdown, rows: 16
-```
-
-### JSON editor
-
-- `:json` (renders the engine’s JSON editor partial)
-
-```ruby
-field :settings, type: :json
-```
-
-### Code editor
-
-- `:code` (monospace editor container; enhanced by engine JS)
-
-```ruby
-field :ruby_code, type: :code, rows: 20
-```
-
-### Label (read-only)
-
-- `:label` renders a badge-like value (useful for status fields)
-
-Options:
-
-- `label_color:` Symbol or Proc
-- `label_size:` `:sm`/`:md` or Proc
-
-```ruby
-field :status, type: :label, label_color: ->(r) { r.active? ? :emerald : :slate }, label_size: :sm
-```
-
-## Layout helpers
-
-Inside `form do ... end` you can group fields:
-
-### `section`
-
-```ruby
-section "Billing", description: "Payment settings", collapsible: true do
-  field :stripe_customer_id, readonly: true
-end
-```
-
-### `row`
-
-```ruby
-row cols: 2 do
-  field :first_name
-  field :last_name
-end
-```
-