admin_suite 0.2.8 → 0.2.9

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
-

data/docs/resources.md

@@ -1,237 +0,0 @@
-# Resources
-
-Resources are defined using `Admin::Base::Resource`.
-
-AdminSuite loads resource definition files from `AdminSuite.config.resource_globs`
-(defaults include `config/admin_suite/resources/*.rb` and `app/admin/resources/*.rb`).
-
-## Create a resource
-
-A resource is a Ruby class under `Admin::Resources` ending in `Resource`.
-
-Example:
-
-```ruby
-# config/admin_suite/resources/user.rb
-module Admin
-  module Resources
-    class UserResource < Admin::Base::Resource
-      model ::User
-      portal :ops
-      section :accounts
-
-      nav label: "Users", icon: "users", order: 10
-
-      index do
-        searchable :email, :name
-        sortable :created_at, :email, default: :created_at, direction: :desc
-        paginate 50
-
-        columns do
-          column :id
-          column :email
-          column :created_at
-          column :admin, type: :toggle, toggle_field: :admin, header: "Admin?"
-          column :status, type: :label, label_color: ->(u) { u.active? ? :emerald : :slate }, label_size: :sm
-        end
-
-        filters do
-          filter :search, type: :text, placeholder: "Search users..."
-          filter :status, type: :select, options: [["Active", "active"], ["Inactive", "inactive"]]
-        end
-
-        stats do
-          stat :total, -> { User.count }, color: :slate
-          stat :new_24h, -> { User.where("created_at > ?", 24.hours.ago).count }, color: :emerald
-        end
-      end
-
-      form do
-        section "Basics", description: "Core account fields" do
-          field :email, type: :email, required: true
-          field :name, required: true
-        end
-
-        row cols: 2 do
-          field :admin, type: :toggle, help: "Grants access to internal tools."
-          field :status, type: :select, collection: [["Active", "active"], ["Inactive", "inactive"]]
-        end
-      end
-
-      show do
-        main do
-          panel :details, title: "User details", fields: %i[email name status created_at]
-          panel :activity, title: "Activity", render: :custom_activity_timeline
-        end
-
-        sidebar do
-          panel :summary, title: "Summary", fields: %i[id admin]
-        end
-      end
-
-      actions do
-        action :reset_password, label: "Reset password", icon: "key", confirm: "Send reset email?"
-      end
-    end
-  end
-end
-```
-
-## Core DSL
-
-### Model
-
-```ruby
-model ::User
-```
-
-### Navigation placement
-
-```ruby
-portal :ops
-section :accounts
-```
-
-These determine:
-
-- URL: `/:portal/:resource_name`
-- Sidebar placement: portal group → section group → resource link
-
-### Navigation metadata
-
-```ruby
-nav label: "Users", icon: "users", order: 10
-```
-
-Also available as convenience setters:
-
-```ruby
-label "Users"
-icon "users"
-order 10
-```
-
-## Index DSL (`index do ... end`)
-
-### Search
-
-```ruby
-searchable :name, :email
-```
-
-Search uses `ILIKE` across the configured fields.
-
-### Sort
-
-```ruby
-sortable :created_at, :email, default: :created_at, direction: :desc
-```
-
-### Pagination
-
-```ruby
-paginate 25
-```
-
-### Columns
-
-```ruby
-columns do
-  column :email
-  column :job_listings, ->(u) { u.job_listings.count }
-end
-```
-
-`column` options:
-
-- `header:` string (defaults to a humanized name)
-- `class:` css class for the cell
-- `render:` custom render key (advanced)
-- `type:` `:toggle` or `:label` (special rendering)
-- `toggle_field:` field to flip when `type: :toggle`
-- `label_color:` color for `type: :label` (Symbol or Proc)
-- `label_size:` `:sm`/`:md` (or Proc)
-- `sortable:` boolean (reserved for future per-column sorting UI)
-
-### Filters
-
-```ruby
-filters do
-  filter :status, type: :select, options: [["Active", "active"], ["Inactive", "inactive"]]
-end
-```
-
-Filter options:
-
-- `type:` (default `:text`)
-- `label:`
-- `placeholder:`
-- `options:` / `collection:` (for select-like UI)
-- `field:` which model field to filter on (defaults to the filter name)
-- `apply:` Proc that receives the scope (advanced)
-
-### Stats
-
-```ruby
-stats do
-  stat :total, -> { User.count }, color: :slate
-end
-```
-
-## Form DSL (`form do ... end`)
-
-```ruby
-form do
-  field :name, required: true
-  field :website, type: :url
-end
-```
-
-See [Fields](fields.md) for supported types and options.
-
-AdminSuite also supports basic layout helpers in forms:
-
-- `section "Title" do ... end`
-- `row cols: 2 do ... end`
-
-## Show DSL (`show do ... end`)
-
-Show is section-based. Sections can live in the main column or sidebar.
-
-```ruby
-show do
-  main do
-    panel :details, title: "Details", fields: %i[name email]
-    panel :related, title: "Projects", association: :projects, display: :table, columns: %i[id name status], paginate: true
-  end
-
-  sidebar do
-    panel :meta, title: "Meta", fields: %i[id created_at updated_at]
-  end
-end
-```
-
-Panel options:
-
-- `title:` (defaults to a humanized name)
-- `fields:` array of field names to display
-- `render:` custom renderer key (see `custom_renderers` in [Configuration](configuration.md))
-- `association:` association name to render (`has_many`, `belongs_to`, etc.)
-- `display:` `:list` (default), `:table`, or `:cards` for associations
-- `columns:` columns for association `:table` display
-- `link_to:` helper method name to build links for association items (optional)
-- `paginate:` boolean, enables pagination within the association section
-- `per_page:` items per page for association pagination
-- `limit:` max items (if not paginating)
-- `collapsible:` / `collapsed:` (reserved for future UI toggles)
-
-## Actions DSL (`actions do ... end`)
-
-```ruby
-actions do
-  action :reindex, label: "Reindex", method: :post, confirm: "Reindex this record?"
-end
-```
-
-See [Actions](actions.md) for how actions execute and how to define handlers.
-

data/docs/theming.md

@@ -1,63 +0,0 @@
-# Theming & assets
-
-AdminSuite is designed to work in two modes:
-
-1. **Engine-build mode (default)**: AdminSuite builds and ships its own Tailwind CSS into your host app at `assets:precompile` time.
-2. **Host-themed mode (optional)**: your host app includes a stylesheet after AdminSuite for branding/overrides.
-
-## Theme colors (`config.theme`)
-
-AdminSuite uses CSS variables scoped to `body.admin-suite`.
-
-```ruby
-AdminSuite.configure do |config|
-  config.theme = { primary: :emerald, secondary: :cyan }
-end
-```
-
-### Allowed values
-
-- **Named colors**: symbols/strings like `:indigo`, `:emerald`, `:cyan`, `:amber`, `:violet`, `:slate`, etc.
-- **Hex**: `"#4f46e5"` (uses that exact color as primary/secondary in key places)
-
-The theme primarily drives:
-
-- Primary links/buttons (`--admin-suite-primary`, `--admin-suite-primary-hover`)
-- Sidebar gradient (`--admin-suite-sidebar-from/via/to`)
-
-## Host stylesheet (`config.host_stylesheet`)
-
-If your host app already has Tailwind (or you want to override the engine UI), you can include an additional stylesheet after AdminSuite in the engine layout:
-
-```ruby
-AdminSuite.configure do |config|
-  config.host_stylesheet = :app
-end
-```
-
-This calls `stylesheet_link_tag :app` after `admin_suite.css` and `admin_suite_tailwind.css`.
-
-## Tailwind build
-
-AdminSuite writes an engine stylesheet into your host app during `assets:precompile`:
-
-- Input: `AdminSuite::Engine.root/app/assets/tailwind/admin_suite.css`
-- Output: `Rails.root/app/assets/builds/admin_suite_tailwind.css`
-
-In development, the engine also makes a best-effort to create the output file if it’s missing, so the UI stays usable.
-
-## Icons
-
-AdminSuite uses lucide icons by default via `lucide-rails`.
-
-If you need a different icon provider:
-
-```ruby
-AdminSuite.configure do |config|
-  config.icon_renderer = ->(name, view, **opts) do
-    # return HTML-safe SVG (string or ActiveSupport::SafeBuffer)
-    view.content_tag(:span, name, class: opts[:class])
-  end
-end
-```
-

data/docs/troubleshooting.md

@@ -1,50 +0,0 @@
-# Troubleshooting
-
-## “My resources don’t show up in the sidebar”
-
-Checklist:
-
-- Your resource class:
-  - is under `Admin::Resources`
-  - ends with `Resource` (e.g. `UserResource`)
-  - sets both `portal :...` and `section :...`
-- The file is located under one of the configured `resource_globs` paths (see [Configuration](configuration.md)).
-
-In development, AdminSuite loads resources on-demand when building navigation. In non-development environments, you should ensure your resource files are loaded at boot (using the globs) and are not excluded by your deployment setup.
-
-## “Constant not found” / Zeitwerk errors for host DSL files
-
-If you store AdminSuite DSL files under `app/admin_suite/**` in the host app, those files are not constant definitions.
-
-AdminSuite ignores `Rails.root/app/admin_suite` in Zeitwerk to prevent eager-load errors. If you still see issues:
-
-- Ensure the DSL folder really is `app/admin_suite` (not a different path)
-- Prefer `config/admin_suite/resources/*.rb` and `config/admin_suite/portals/*.rb` for DSL files
-
-## “Docs viewer shows no files”
-
-- Confirm `AdminSuite.config.docs_path` exists
-- Ensure files are `*.md`
-- Visit `/docs` relative to your mount path (e.g. `/internal/admin/docs`)
-
-## “Tailwind styles are missing in production”
-
-AdminSuite expects `assets:precompile` to run and generate:
-
-- `app/assets/builds/admin_suite_tailwind.css` in your host app
-
-If you don’t run precompile in your deployment pipeline, you can:
-
-- Start running `assets:precompile`, or
-- Build the file manually by running:
-
-```bash
-bin/rails admin_suite:tailwind:build
-```
-
-## “Icons don’t render”
-
-AdminSuite defaults to `lucide-rails`.
-
-If your host app excludes it, set `AdminSuite.config.icon_renderer` to provide icons (see [Theming & assets](theming.md)).
-