plutonium 0.34.1 → 0.35.0

data/docs/concepts/auto-detection.md

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

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

data/docs/concepts/packages-portals.md

@@ -1,304 +0,0 @@
-# Packages and Portals
-
-Plutonium organizes applications using two types of packages: **Feature Packages** for business logic and **Portal Packages** for web interfaces.
-
-## Why Packages?
-
-Packages provide:
-- **Modularity** - Features are isolated and self-contained
-- **Reusability** - Share features across multiple interfaces
-- **Scalability** - Large apps stay organized
-- **Team collaboration** - Teams can own specific packages
-
-## Feature Packages
-
-Feature packages contain your business logic: models, definitions, policies, interactions, and controllers.
-
-### Creating a Feature Package
-
-```bash
-rails generate pu:pkg:package blogging
-```
-
-This creates:
-
-```
-packages/blogging/
-├── app/
-│   ├── controllers/blogging/
-│   ├── definitions/blogging/
-│   ├── interactions/blogging/
-│   ├── models/blogging/
-│   ├── policies/blogging/
-│   └── views/blogging/
-└── lib/
-    └── engine.rb
-```
-
-### Feature Package Structure
-
-```ruby
-# packages/blogging/lib/engine.rb
-module Blogging
-  class Engine < Rails::Engine
-    include Plutonium::Package::Engine
-
-    # Package configuration here
-  end
-end
-```
-
-### Adding Resources to a Feature Package
-
-```bash
-rails generate pu:res:scaffold Post title:string body:text --dest=blogging
-```
-
-Resources are namespaced under the package:
-
-```ruby
-# packages/blogging/app/models/blogging/post.rb
-module Blogging
-  class Post < Blogging::ResourceRecord
-  end
-end
-```
-
-## Portal Packages
-
-Portal packages are web interfaces that expose resources to users. Each portal can have its own authentication, authorization, and UI customizations.
-
-### Creating a Portal Package
-
-```bash
-rails generate pu:pkg:portal admin
-```
-
-This creates:
-
-```
-packages/admin_portal/
-├── app/
-│   ├── controllers/admin_portal/
-│   └── views/admin_portal/
-├── config/
-│   └── routes.rb
-├── lib/
-│   └── admin_portal/
-│       └── engine.rb
-├── admin_portal.gemspec
-└── Gemfile
-```
-
-### Portal Engine
-
-```ruby
-# packages/admin_portal/lib/admin_portal/engine.rb
-module AdminPortal
-  class Engine < Rails::Engine
-    include Plutonium::Portal::Engine
-
-    config.after_initialize do
-      # Optional: Scope to an entity (multi-tenancy)
-      scope_to_entity Organization
-    end
-  end
-end
-```
-
-### Portal Authentication
-
-Authentication is configured in the controller concern:
-
-```ruby
-# packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb
-module AdminPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-      include Plutonium::Auth::Rodauth(:admin)
-    end
-  end
-end
-```
-
-### Connecting Resources to Portals
-
-```bash
-rails generate pu:res:conn Blogging::Post --dest=admin_portal
-```
-
-This:
-1. Registers the resource in portal routes
-2. Creates portal-specific controller
-3. Creates portal-specific policy with attribute permissions
-
-## Multiple Portals
-
-A common pattern is having different portals for different user types:
-
-```
-packages/
-├── admin_portal/      # Full access for administrators
-├── author_portal/     # Content management for authors
-└── customer_portal/   # Public-facing interface
-```
-
-Each portal can:
-- Use different authentication
-- Show different fields
-- Apply different policies
-- Have unique UI customization
-
-### Example: Same Resource, Different Portals
-
-```ruby
-# Admin sees everything
-# packages/admin_portal/app/policies/admin_portal/blogging/post_policy.rb
-module AdminPortal
-  module Blogging
-    class PostPolicy < ::Blogging::PostPolicy
-      def read?
-        true  # Admins see all posts
-      end
-    end
-  end
-end
-
-# Authors see only their posts
-# packages/author_portal/app/policies/author_portal/blogging/post_policy.rb
-module AuthorPortal
-  module Blogging
-    class PostPolicy < ::Blogging::PostPolicy
-      def read?
-        record.user_id == user.id
-      end
-    end
-  end
-end
-```
-
-## Package Dependencies
-
-Feature packages can depend on each other:
-
-```ruby
-# packages/blogging/blogging.gemspec
-Gem::Specification.new do |spec|
-  spec.add_dependency "users"  # Depends on users package
-end
-```
-
-## Mounting Packages
-
-Packages are mounted in the main application routes:
-
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  mount AdminPortal::Engine, at: "/admin"
-  mount AuthorPortal::Engine, at: "/author"
-  mount CustomerPortal::Engine, at: "/"
-end
-```
-
-## Authentication per Portal
-
-Each portal can use different authentication via its controller concern:
-
-```ruby
-# packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb
-module AdminPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-      include Plutonium::Auth::Rodauth(:admin)
-    end
-  end
-end
-
-# packages/customer_portal/app/controllers/customer_portal/concerns/controller.rb
-module CustomerPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-      include Plutonium::Auth::Rodauth(:customer)
-    end
-  end
-end
-```
-
-## Entity Scoping (Multi-tenancy)
-
-Portals can be scoped to an entity:
-
-```ruby
-module CustomerPortal
-  class Engine < Rails::Engine
-    include Plutonium::Portal::Engine
-
-    config.after_initialize do
-      # All resources scoped to current organization
-      scope_to_entity Organization
-    end
-  end
-end
-```
-
-With entity scoping:
-- All queries automatically filter by entity
-- New records automatically belong to entity
-- Users can only access their entity's data
-
-## Portal Customization
-
-### Custom Layouts
-
-```ruby
-# packages/admin_portal/app/views/layouts/admin_portal/application.rb
-module AdminPortal
-  class ApplicationLayout < Plutonium::UI::Layout::Application
-    def render_logo
-      img(src: asset_path("admin-logo.svg"))
-    end
-  end
-end
-```
-
-### Portal-Specific Definitions
-
-```ruby
-# packages/admin_portal/app/definitions/admin_portal/blogging/post_definition.rb
-module AdminPortal
-  module Blogging
-    class PostDefinition < ::Blogging::PostDefinition
-      # Add admin-specific fields
-      field :internal_notes, as: :text
-    end
-  end
-end
-```
-
-## Best Practices
-
-### 1. One Feature, One Package
-Keep packages focused. A "blogging" package shouldn't handle user management.
-
-### 2. Portal-Specific Overrides
-Put customizations in the portal package, not the feature package.
-
-### 3. Shared Logic in Features
-Business logic goes in feature packages, UI customization in portals.
-
-### 4. Clear Naming
-- Feature packages: noun (blogging, inventory, billing)
-- Portal packages: role + portal (admin_portal, customer_portal)
-
-## Related Topics
-
-- [Architecture](./architecture) - How layers work together
-- [Resources](./resources) - Understanding resources
-- [Portal Reference](/reference/portal/) - Portal configuration