admin_suite 0.2.8 → 0.3.0

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
-```
-

data/docs/installation.md

@@ -1,80 +0,0 @@
-# Installation
-
-## Requirements
-
-- Ruby **3.2+**
-- Rails **8.0+**
-
-AdminSuite is a mountable engine. You mount it under a path in your host app’s `config/routes.rb`.
-
-## Add the gem
-
-In your host app `Gemfile`:
-
-```ruby
-gem "admin_suite"
-```
-
-Then:
-
-```bash
-bundle install
-```
-
-## Install into your app
-
-Run the install generator (creates an initializer and mounts the engine):
-
-```bash
-bin/rails g admin_suite:install
-```
-
-To mount at a custom path:
-
-```bash
-bin/rails g admin_suite:install --mount-path=/internal/admin
-```
-
-This will:
-
-- Create `config/initializers/admin_suite.rb`
-- Add a route like `mount AdminSuite::Engine => "/internal/admin"`
-
-## First run checklist
-
-- **Auth**: set `config.authenticate` so only permitted users can access AdminSuite.
-- **Actor**: set `config.current_actor` if you want actions/auditing to know “who did it”.
-- **Resources**: add at least one resource definition file (see [Resources](resources.md)).
-- **Portals**: set up portal metadata and dashboards (see [Portals](portals.md)).
-
-## Assets (CSS/JS)
-
-AdminSuite ships with:
-
-- A small baseline stylesheet (`admin_suite.css`)
-- A compiled Tailwind stylesheet (`admin_suite_tailwind.css`) that is built into the host app at asset precompile time
-- Engine-provided Stimulus controllers via importmap
-
-### CSS build behavior
-
-When your app runs `assets:precompile`, AdminSuite automatically runs:
-
-- `admin_suite:tailwind:build` → writes `app/assets/builds/admin_suite_tailwind.css` in your **host app**
-
-So in production you typically just need to ensure your deployment runs `assets:precompile` as usual.
-
-### Host stylesheet overrides (optional)
-
-If your app already uses Tailwind (or you want custom branding), you can include your app stylesheet after AdminSuite:
-
-- Set `config.host_stylesheet` (see [Theming & assets](theming.md))
-
-## Routes and URLs
-
-Assuming you mounted at `/internal/admin`:
-
-- `/internal/admin` → AdminSuite dashboard
-- `/internal/admin/docs` → docs viewer (optional)
-- `/internal/admin/:portal` → portal dashboard (optional)
-- `/internal/admin/:portal/:resource_name` → resource index
-

data/docs/portals.md

@@ -1,140 +0,0 @@
-# Portals & dashboards
-
-AdminSuite navigation is organized by **portal** and **section**:
-
-- A **portal** is the top-level grouping (e.g. `:ops`, `:ai`)
-- A **section** is a grouping within a portal (e.g. `:billing`, `:users`)
-- A **resource** belongs to exactly one portal + section via the resource DSL
-
-You can configure portals in two complementary ways:
-
-1. **Portal metadata** via `AdminSuite.config.portals` (label/icon/color/order)
-2. **Portal DSL** via `AdminSuite.portal(:key) { ... }` (metadata + dashboard layout)
-
-## Portal metadata (`config.portals`)
-
-```ruby
-AdminSuite.configure do |config|
-  config.portals = {
-    ops: { label: "Ops", icon: "settings", color: :amber, order: 10 },
-    ai: { label: "AI", icon: "cpu", color: :cyan, order: 20 }
-  }
-end
-```
-
-### Portal fields
-
-- `label` (String): display label
-- `icon` (String/Symbol): lucide icon name (e.g. `"settings"`)
-- `color` (Symbol/String): used for accents (`:amber`, `:emerald`, `:cyan`, `:violet`, `:slate`)
-- `order` (Integer): sort order in the root dashboard and sidebar
-- `description` (String, optional): shown on the root dashboard cards when present
-
-## Portal DSL (`AdminSuite.portal`)
-
-Portal DSL files are loaded from `AdminSuite.config.portal_globs` (defaults include
-`config/admin_suite/portals/*.rb`, `app/admin/portals/*.rb`, `app/admin_suite/portals/*.rb`).
-
-Example file:
-
-```ruby
-# config/admin_suite/portals/ops.rb
-AdminSuite.portal :ops do
-  label "Ops Portal"
-  icon "settings"
-  color :amber
-  order 10
-  description "Operational tools and internal resources."
-
-  dashboard do
-    row do
-      stat_panel "New users (24h)", -> { User.where("created_at > ?", 24.hours.ago).count }, color: :emerald, span: 3
-      stat_panel "Failed jobs", -> { SolidQueue::FailedExecution.count }, color: :red, span: 3
-    end
-
-    row do
-      recent_panel "Recent signups", scope: -> { User.order(created_at: :desc).limit(5) }, span: 6
-      table_panel "Queue summary",
-        rows: -> { SolidQueue::Job.order(created_at: :desc).limit(10) },
-        columns: %i[id class_name created_at],
-        span: 6
-    end
-  end
-end
-```
-
-## Dashboard DSL
-
-The dashboard DSL is available inside `portal.dashboard do ... end`.
-
-- `dashboard` contains `row { ... }`
-- each `row` contains one or more `panel(...)` calls
-
-### Panel helpers
-
-These are convenience helpers that all create a `panel` under the hood:
-
-- `stat_panel(title, value=nil, span: nil, **options, &block)`
-- `health_panel(title, status: nil, metrics: nil, span: nil, **options, &block)`
-- `chart_panel(title, data: nil, span: nil, **options, &block)`
-- `cards_panel(title, resources: nil, span: nil, **options, &block)`
-- `recent_panel(title, scope: nil, link: nil, span: nil, **options, &block)`
-- `table_panel(title, rows: nil, columns: nil, span: nil, **options, &block)`
-
-### `span`
-
-`span` controls width in a 12-column grid. Typical values: `3`, `4`, `6`, `12`.
-
-## Portal pages
-
-Once mounted, portal pages are served at:
-
-- `/:portal` (relative to the mount path)
-
-Example:
-
-- `/internal/admin/ops`
-- `/internal/admin/ai`
-
-## Root dashboard (`AdminSuite.root_dashboard`)
-
-The engine root (`/`, relative to the mount path) renders a default dashboard (portal cards + basic stats).
-
-To customize it, create a dashboard definition file (loaded from `AdminSuite.config.dashboard_globs`, which defaults to paths like `config/admin_suite/dashboard.rb` and `app/admin_suite/dashboard.rb`):
-
-```ruby
-# config/admin_suite/dashboard.rb
-AdminSuite.configure do |config|
-  config.root_dashboard_title = "Developer Portal"
-  config.root_dashboard_description = "Internal tools for managing application resources."
-end
-
-AdminSuite.root_dashboard do
-  row do
-    cards_panel "Portals",
-      span: 12,
-      variant: :portals,
-      resources: ->(view) do
-        view.navigation_items
-          .sort_by { |(_k, meta)| (meta[:order] || 100).to_i }
-          .map do |portal_key, portal|
-            {
-              key: portal_key,
-              label: portal[:label] || portal_key.to_s.humanize,
-              description: portal[:description],
-              color: view.portal_color(portal_key),
-              icon: portal[:icon],
-              path: view.portal_path(portal: portal_key),
-              count: (portal[:sections] || {}).values.sum { |s| Array(s[:items]).size }
-            }
-          end
-      end
-  end
-
-  row do
-    stat_panel "Portals", ->(view) { view.navigation_items.keys.count }, span: 6, variant: :mini, color: :slate
-    stat_panel "Resources", -> { Admin::Base::Resource.registered_resources.count }, span: 6, variant: :mini, color: :slate
-  end
-end
-```
-

data/docs/releasing.md

@@ -1,67 +0,0 @@
-# Releasing
-
-This page is intended for maintainers publishing `admin_suite` to RubyGems.
-
-## Automated Release Process (Recommended)
-
-The gem is automatically published to RubyGems when changes are merged to `main`, provided the version has been bumped.
-
-### Steps
-
-1. **Bump the version**
-   - Update `lib/admin_suite/version.rb`
-
-2. **Update changelog**
-   - Add an entry to `CHANGELOG.md`
-
-3. **Create a PR and get it merged**
-   - The CI workflow will run tests automatically on the PR
-   - Once merged to `main`, after CI passes, the publish workflow will:
-     - Check if the version already exists on RubyGems
-     - Build and publish the gem (if it's a new version)
-     - Create a Git tag for the release (if it doesn't already exist)
-     - Create a GitHub Release with notes extracted from `CHANGELOG.md`, or auto-generated from commits since the previous tag if no CHANGELOG entry exists
-
-### Requirements
-
-- The `RUBYGEMS_API_KEY` secret must be configured in the repository settings
-- The version in `lib/admin_suite/version.rb` must be unique (not already published)
-
-## Manual Release Process
-
-If you need to publish manually:
-
-1. Bump the version
-   - Update `lib/admin_suite/version.rb`
-
-2. Update changelog
-   - Add an entry to `CHANGELOG.md`
-
-3. Run tests and build the gem
-
-```bash
-bundle exec rake test
-gem build admin_suite.gemspec
-```
-
-4. Tag the release
-
-```bash
-git tag -a "vX.Y.Z" -m "AdminSuite vX.Y.Z"
-git push --tags
-```
-
-5. Publish to RubyGems
-
-```bash
-gem push "admin_suite-X.Y.Z.gem"
-```
-
-## Notes
-
-- RubyGems commonly requires MFA/OTP for pushes (this gem is configured with `rubygems_mfa_required`)
-- The automated workflow uses a GitHub Actions bot to push tags and create GitHub Releases
-- The publish workflow only runs after the CI workflow completes successfully
-- GitHub Release notes are sourced from the matching version section in `CHANGELOG.md`; if no entry exists, they are auto-generated from commits since the previous tag; a plain "Release vX.Y.Z" string is used only as a final fallback when no previous tag or commit-generated notes are available
-- You can manually trigger the publish workflow from the GitHub Actions tab if needed
-