admin_suite 0.2.8 → 0.3.0

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)).
-