admin_suite 0.1.0 → 0.1.1

data/docs/fields.md

@@ -0,0 +1,188 @@
+# 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

@@ -0,0 +1,80 @@
+# 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

@@ -0,0 +1,98 @@
+# 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`
+

data/docs/releasing.md

@@ -0,0 +1,38 @@
+# Releasing
+
+This page is intended for maintainers publishing `admin_suite` to RubyGems.
+
+## Checklist
+
+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. (Recommended) 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`).
+

data/docs/resources.md

@@ -0,0 +1,237 @@
+# 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

@@ -0,0 +1,63 @@
+# 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
+```
+