plutonium 0.33.1 → 0.34.0

data/docs/concepts/architecture.md

@@ -0,0 +1,226 @@
+# Architecture
+
+Plutonium follows a layered architecture where each layer has a specific responsibility. This separation makes applications easier to understand, test, and maintain.
+
+## The Four Layers
+
+### 1. Model Layer
+
+The Model layer handles **data and business rules**.
+
+```ruby
+class Post < ResourceRecord
+  belongs_to :user
+  has_many :comments
+
+  validates :title, presence: true
+  validates :body, presence: true
+
+  scope :published, -> { where(published: true) }
+end
+```
+
+Responsibilities:
+- Database schema and migrations
+- Validations
+- Associations
+- Scopes and queries
+- Core business logic
+
+### 2. Definition Layer
+
+The Definition layer controls **how resources render**.
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Fields shown in forms
+  field :title
+  field :body, as: :rich_text
+  field :published, as: :switch
+
+  # Columns shown in tables
+  column :title, sortable: true
+  column :published
+  column :created_at
+
+  # Custom actions
+  action :publish, interaction: PublishPost
+end
+```
+
+Responsibilities:
+- Which fields appear in forms
+- How fields are rendered (input types)
+- Table column configuration
+- Search and filtering
+- Custom actions
+- Field groups and layout
+
+### 3. Policy Layer
+
+The Policy layer controls **authorization**.
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  def read?
+    record.published? || owner?
+  end
+
+  def update?
+    owner?
+  end
+
+  def permitted_attributes_for_update
+    [:title, :body, :published]
+  end
+
+  def relation_scope(relation)
+    relation.where(published: true).or(relation.where(user: user))
+  end
+end
+```
+
+Responsibilities:
+- Action permissions (can user perform action?)
+- Attribute permissions (which fields can user see/modify?)
+- Collection scoping (which records can user access?)
+- Multi-tenancy isolation
+
+### 4. Controller Layer
+
+The Controller layer handles **HTTP requests**.
+
+```ruby
+class PostsController < Plutonium::Resource::Controller
+  private
+
+  def build_resource
+    super.tap do |post|
+      post.user = current_user
+    end
+  end
+
+  def after_create_success
+    notify_subscribers(@resource)
+    super
+  end
+end
+```
+
+Responsibilities:
+- CRUD actions
+- Request/response handling
+- Resource building hooks
+- Redirects and rendering
+- Format handling (HTML, JSON, etc.)
+
+## Request Flow
+
+When a request comes in, it flows through the layers:
+
+```
+1. REQUEST arrives at Portal
+   ↓
+2. CONTROLLER receives request
+   ↓
+3. POLICY checks authorization
+   ↓
+4. DEFINITION determines rendering
+   ↓
+5. MODEL provides data
+   ↓
+6. RESPONSE rendered and returned
+```
+
+### Example: Viewing a Post
+
+```
+GET /admin/posts/1
+
+1. AdminPortal routes to PostsController#show
+2. PostsController loads Post.find(1)
+3. PostPolicy#read? checks if user can view
+4. PostDefinition provides field configuration
+5. UI renders the post display
+6. HTML response returned
+```
+
+### Example: Creating a Post
+
+```
+POST /admin/posts
+
+1. AdminPortal routes to PostsController#create
+2. PostsController builds new Post
+3. PostPolicy#create? checks if user can create
+4. PostPolicy#permitted_attributes_for_create filters params
+5. Post validates and saves
+6. Redirect to show page
+```
+
+## Layer Interaction
+
+Layers communicate through well-defined interfaces:
+
+```ruby
+# Controller asks Policy
+policy = policy_for(resource)
+policy.authorize!(:update)
+
+# Controller uses Definition
+definition = definition_for(resource)
+definition.fields_for(:form)
+
+# Policy uses Model
+def owner?
+  record.user_id == user.id
+end
+```
+
+## Customization Points
+
+Each layer provides hooks for customization:
+
+### Model Hooks
+- Callbacks (before_save, after_create, etc.)
+- Custom methods
+- Scopes
+
+### Definition Hooks
+- Field configuration
+- Custom renderers
+- Conditional display
+
+### Policy Hooks
+- Custom permission methods
+- Attribute filtering
+- Scope customization
+
+### Controller Hooks
+- `build_resource` - Customize resource initialization
+- `before_action` - Standard Rails callbacks
+- `after_*_success/failure` - Action result hooks
+
+## Why This Architecture?
+
+### 1. Separation of Concerns
+Each layer has one job. Forms don't know about authorization. Policies don't know about rendering.
+
+### 2. Testability
+Each layer can be tested in isolation:
+- Model specs test validations and queries
+- Policy specs test authorization
+- Definition specs test field configuration
+- Controller specs test request handling
+
+### 3. Reusability
+Definitions and policies can be shared across portals. Models are independent of the UI.
+
+### 4. Maintainability
+Changes to authorization don't affect forms. UI changes don't affect data logic.
+
+## Related Topics
+
+- [Resources](./resources) - Understanding resource classes
+- [Packages and Portals](./packages-portals) - Organizing your application
+- [Auto-Detection](./auto-detection) - How defaults are determined

data/docs/concepts/auto-detection.md

@@ -0,0 +1,254 @@
+# Auto-Detection
+
+Plutonium automatically detects configuration from your models, reducing boilerplate code. You only write configuration when you need to override the defaults.
+
+## How Auto-Detection Works
+
+When Plutonium renders a resource, it examines:
+1. Database columns (types, constraints)
+2. Model validations
+3. Model associations
+4. Existing configuration
+
+From this, it determines sensible defaults for forms, tables, and displays.
+
+## Field Detection
+
+### From Column Types
+
+| Column Type | Default Input | Default Display |
+|-------------|---------------|-----------------|
+| `string` | Text input | Text |
+| `text` | Textarea | Formatted text |
+| `integer` | Number input | Number |
+| `float`/`decimal` | Decimal input | Formatted number |
+| `boolean` | Checkbox | Yes/No badge |
+| `date` | Date picker | Formatted date |
+| `datetime` | Datetime picker | Formatted datetime |
+| `time` | Time picker | Formatted time |
+| `json`/`jsonb` | JSON editor | JSON display |
+
+### From Constraints
+
+```ruby
+# Schema
+t.string :email, null: false
+
+# Auto-detects: required field
+field :email  # Marked as required in form
+```
+
+### From Validations
+
+```ruby
+# Model
+validates :title, presence: true, length: { maximum: 100 }
+
+# Auto-detects:
+# - Required field
+# - Max length constraint
+```
+
+## Association Detection
+
+### belongs_to
+
+```ruby
+# Model
+belongs_to :user
+
+# Auto-detects:
+# - Select input with user options
+# - Link to user in display
+# - Automatic eager loading in queries
+```
+
+### has_many
+
+```ruby
+# Model
+has_many :comments
+
+# Auto-detects:
+# - Association panel on detail page
+# - Count display in tables (optional)
+# - Nested forms support (if configured)
+```
+
+### has_one
+
+```ruby
+# Model
+has_one :profile
+
+# Auto-detects:
+# - Inline display on detail page
+# - Nested form support
+```
+
+## Validation Detection
+
+| Validation | Effect |
+|------------|--------|
+| `presence` | Field marked required |
+| `length` | Min/max constraints |
+| `numericality` | Number input with constraints |
+| `inclusion` | Select input with options |
+| `format` | Pattern attribute on input |
+
+```ruby
+# Model
+validates :status, inclusion: { in: %w[draft published archived] }
+
+# Auto-detects: Select with options
+field :status  # Renders as select with draft/published/archived options
+```
+
+## Overriding Defaults
+
+Auto-detection provides a starting point. Override when needed:
+
+### Field Type Override
+
+```ruby
+# Auto-detected: text input
+# Override: rich text editor
+field :body, as: :rich_text
+```
+
+### Field Options
+
+```ruby
+# Auto-detected: select with model options
+# Override: custom collection
+field :user, collection: -> { User.active.pluck(:name, :id) }
+```
+
+### Hiding Fields
+
+```ruby
+# Exclude from forms
+exclude_from_form :created_at, :updated_at
+
+# Or per-field
+field :user, as: :hidden
+```
+
+### Required Override
+
+```ruby
+# Model allows null, but form requires it
+field :nickname, required: true
+```
+
+## Table Column Detection
+
+By default, tables show a subset of fields. Plutonium prioritizes:
+1. Non-association fields
+2. Non-text fields (text is too long for tables)
+3. Fields with meaningful data
+
+### Override Columns
+
+```ruby
+# Explicitly set columns
+column :title
+column :published
+column :user
+column :created_at
+```
+
+## Search Detection
+
+Plutonium can auto-detect searchable fields:
+- String columns are searchable by default
+- Text columns can be included
+
+### Override Search
+
+```ruby
+# Custom search implementation
+search do |scope, query|
+  scope.where("title ILIKE ?", "%#{query}%")
+end
+```
+
+## Filter Detection
+
+For associations, Plutonium can auto-generate filters:
+
+```ruby
+# Auto-detected from belongs_to :user
+filter :user  # Select filter with user options
+```
+
+### Override Filters
+
+```ruby
+filter :status, as: :select, collection: %w[draft published archived]
+filter :created_at, as: :date_range
+```
+
+## When Auto-Detection Runs
+
+Auto-detection happens at render time, not definition time. This means:
+
+1. Changes to models are reflected immediately
+2. New columns appear in forms automatically
+3. Removed columns disappear from forms
+
+## Caching
+
+In production, auto-detection results are cached for performance. Clear the cache after schema changes:
+
+```ruby
+Rails.cache.clear
+```
+
+## Best Practices
+
+### 1. Start with Defaults
+Let auto-detection do its job. Only configure what you need to change.
+
+### 2. Be Explicit When It Matters
+For important forms, explicitly declare fields to prevent surprise changes:
+
+```ruby
+# Explicit field list
+field :title
+field :body
+field :published
+
+# vs relying on auto-detection
+# (new columns would appear automatically)
+```
+
+### 3. Use Models as Documentation
+Your model's validations and associations document the expected UI:
+
+```ruby
+class Post < ResourceRecord
+  belongs_to :user                    # Select input
+  validates :title, presence: true    # Required field
+  validates :status, inclusion: {...} # Select options
+end
+```
+
+### 4. Test After Schema Changes
+After adding/removing columns, verify forms still work correctly.
+
+## Debugging Auto-Detection
+
+To see what Plutonium detected:
+
+```ruby
+definition = PostDefinition.new
+puts definition.detected_fields.inspect
+puts definition.detected_columns.inspect
+```
+
+## Related Topics
+
+- [Fields Reference](/reference/definition/fields) - All field options
+- [Model Reference](/reference/model/) - Model configuration
+- [Resources](./resources) - Understanding resources

data/docs/concepts/index.md

@@ -0,0 +1,61 @@
+# Core Concepts
+
+This section explains the fundamental concepts behind Plutonium's architecture.
+
+## Overview
+
+Plutonium is built around a few key principles:
+
+1. **Separation of Concerns** - Each layer has a single responsibility
+2. **Convention over Configuration** - Smart defaults, override when needed
+3. **Modularity** - Features organized into independent packages
+4. **Full Customization** - Every layer can be overridden
+
+## Key Concepts
+
+### [Architecture](./architecture)
+How the Model → Definition → Policy → Controller layers work together to create a resource.
+
+### [Resources](./resources)
+What resources are and how they differ from plain Rails models.
+
+### [Packages and Portals](./packages-portals)
+How to organize your application using Feature Packages and Portal Packages.
+
+### [Auto-Detection](./auto-detection)
+How Plutonium automatically discovers fields, associations, and validations.
+
+## The Big Picture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         PORTAL                               │
+│  (Web Interface - routes, authentication, UI customization)  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       CONTROLLER                             │
+│  (HTTP handling - request/response, rendering)               │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                        POLICY                                │
+│  (Authorization - who can do what)                           │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      DEFINITION                              │
+│  (Presentation - how resources render)                       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                        MODEL                                 │
+│  (Data - structure, validations, business rules)             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Each layer builds on the one below it, and each can be customized independently.