plutonium 0.34.1 → 0.35.0

data/docs/concepts/resources.md

@@ -1,224 +0,0 @@
-# Resources
-
-In Plutonium, a **resource** is a complete unit that represents a domain concept. Unlike plain Rails models, a Plutonium resource combines data, presentation, and authorization.
-
-## What Makes a Resource?
-
-A resource consists of four parts:
-
-| Component | Purpose | Example |
-|-----------|---------|---------|
-| **Model** | Data structure and validation | `Post` |
-| **Definition** | How it renders | `PostDefinition` |
-| **Policy** | Who can do what | `PostPolicy` |
-| **Controller** | HTTP handling | `PostsController` |
-
-## Resource Models
-
-Resource models inherit from `ResourceRecord`:
-
-```ruby
-class Post < ResourceRecord
-  belongs_to :user
-  has_many :comments
-
-  validates :title, presence: true
-end
-```
-
-This base class adds:
-- Automatic field introspection
-- Association detection
-- Integration with definitions and policies
-
-## Creating Resources
-
-### Using the Generator
-
-The fastest way to create a resource:
-
-```bash
-rails generate pu:res:scaffold Post title:string body:text published:boolean
-```
-
-This generates:
-- Model with attributes and validations
-- Definition with default configuration
-- Policy with standard permissions
-- Migration
-
-### Manual Creation
-
-You can also create resources manually:
-
-```ruby
-# app/models/post.rb
-class Post < ResourceRecord
-  validates :title, presence: true
-end
-
-# app/definitions/post_definition.rb
-class PostDefinition < Plutonium::Resource::Definition
-end
-
-# app/policies/post_policy.rb
-class PostPolicy < Plutonium::Resource::Policy
-end
-```
-
-## Resource vs Model
-
-| Aspect | Plain Model | Resource |
-|--------|-------------|----------|
-| Inheritance | `ApplicationRecord` | `ResourceRecord` |
-| Fields | Manual configuration | Auto-detected |
-| Authorization | Separate concern | Integrated via Policy |
-| UI | Manual forms/views | Auto-generated |
-| CRUD | Write manually | Generated |
-
-## Resource Discovery
-
-Plutonium automatically discovers resources based on naming conventions:
-
-```
-Post           → PostDefinition, PostPolicy, PostsController
-Blogging::Post → Blogging::PostDefinition, Blogging::PostPolicy
-```
-
-## Field Introspection
-
-Resources automatically detect their fields from the database schema:
-
-```ruby
-# Given this schema:
-create_table :posts do |t|
-  t.string :title, null: false
-  t.text :body
-  t.boolean :published, default: false
-  t.belongs_to :user
-  t.timestamps
-end
-
-# Plutonium auto-detects:
-# - title: string input, required
-# - body: textarea
-# - published: checkbox
-# - user: association select
-# - created_at, updated_at: datetime displays
-```
-
-## Resource Registration
-
-Resources must be registered with a portal to be accessible:
-
-```bash
-rails generate pu:res:conn Post --dest=admin_portal
-```
-
-Or manually in routes:
-
-```ruby
-# packages/admin_portal/config/routes.rb
-AdminPortal::Engine.routes.draw do
-  register_resource ::Post
-end
-```
-
-## Nested Resources
-
-Resources are automatically nested via `belongs_to` associations:
-
-```ruby
-class Comment < ResourceRecord
-  belongs_to :post
-end
-```
-
-When both resources are registered in a portal, Plutonium creates nested URLs like `/posts/:post_id/comments`.
-
-## Resource Features
-
-### Entity Scoping (Multi-tenancy)
-
-Entity scoping is configured on the portal engine, not the model:
-
-```ruby
-# packages/customer_portal/lib/engine.rb
-module CustomerPortal
-  class Engine < Rails::Engine
-    include Plutonium::Portal::Engine
-
-    config.after_initialize do
-      scope_to_entity Organization
-    end
-  end
-end
-```
-
-### Monetary Fields
-
-```ruby
-class Product < ResourceRecord
-  # Store as cents, expose as decimal
-  has_cents :price_cents
-end
-```
-
-## Resource Lifecycle
-
-```
-1. User requests /posts/new
-2. Controller builds new Post instance
-3. Policy checks create? permission
-4. Definition provides form fields
-5. Form rendered to user
-
-6. User submits form
-7. Controller receives params
-8. Policy filters permitted attributes
-9. Model validates and saves
-10. Controller redirects or re-renders
-```
-
-## Best Practices
-
-### Keep Models Thin
-Put business logic in Interactions, not models.
-
-```ruby
-# Good: Model handles data
-class Post < ResourceRecord
-  validates :title, presence: true
-end
-
-# Interaction handles logic
-class PublishPost < Plutonium::Interaction::Base
-  def execute
-    resource.update!(published: true, published_at: Time.current)
-    notify_subscribers
-    succeed(resource)
-  end
-end
-```
-
-### Use Meaningful Scopes
-
-```ruby
-class Post < ResourceRecord
-  scope :published, -> { where(published: true) }
-  scope :recent, -> { order(created_at: :desc) }
-  scope :by_author, ->(user) { where(user: user) }
-end
-```
-
-### Validate at the Right Level
-
-- **Model**: Data integrity (presence, format, uniqueness)
-- **Interaction**: Business rules (can only publish once)
-- **Policy**: Authorization (user must own post)
-
-## Related Topics
-
-- [Architecture](./architecture) - How layers work together
-- [Model Reference](/reference/model/) - Complete model documentation
-- [Definition Reference](/reference/definition/) - Field configuration

data/docs/cookbook/blog.md

@@ -1,411 +0,0 @@
-# Recipe: Blog Application
-
-Build a full-featured blog with posts, comments, categories, and multi-user support.
-
-## Overview
-
-This recipe covers:
-- Post and comment management
-- Categories and tags
-- User roles (admin, author, reader)
-- Publication workflow
-- SEO features
-
-## Architecture
-
-```
-packages/
-├── blogging/           # Feature package
-│   ├── models/
-│   │   ├── post.rb
-│   │   ├── comment.rb
-│   │   ├── category.rb
-│   │   └── tag.rb
-│   ├── definitions/
-│   ├── policies/
-│   └── interactions/
-├── admin_portal/       # Admin interface
-└── public_portal/      # Public blog
-```
-
-## Models
-
-### Post
-
-```ruby
-module Blogging
-  class Post < Blogging::ResourceRecord
-    belongs_to :author, class_name: 'User'
-    belongs_to :category
-    has_many :comments, dependent: :destroy
-    has_many :taggings, dependent: :destroy
-    has_many :tags, through: :taggings
-
-    validates :title, presence: true, length: { maximum: 200 }
-    validates :body, presence: true
-    validates :slug, presence: true, uniqueness: true
-
-    scope :published, -> { where(published: true) }
-    scope :draft, -> { where(published: false) }
-    scope :featured, -> { where(featured: true) }
-    scope :recent, -> { order(published_at: :desc) }
-
-    before_validation :generate_slug, on: :create
-
-    def publish!
-      update!(published: true, published_at: Time.current)
-    end
-
-    def reading_time
-      words_per_minute = 200
-      (body.to_plain_text.split.size / words_per_minute.to_f).ceil
-    end
-
-    private
-
-    def generate_slug
-      self.slug ||= title&.parameterize
-    end
-  end
-end
-```
-
-### Comment
-
-```ruby
-module Blogging
-  class Comment < Blogging::ResourceRecord
-    belongs_to :post
-    belongs_to :author, class_name: 'User'
-    belongs_to :parent, class_name: 'Comment', optional: true
-    has_many :replies, class_name: 'Comment', foreign_key: :parent_id
-
-    validates :body, presence: true
-
-    scope :approved, -> { where(approved: true) }
-    scope :pending, -> { where(approved: false) }
-    scope :root, -> { where(parent_id: nil) }
-  end
-end
-```
-
-### Category
-
-```ruby
-module Blogging
-  class Category < Blogging::ResourceRecord
-    has_many :posts
-
-    validates :name, presence: true, uniqueness: true
-    validates :slug, presence: true, uniqueness: true
-
-    before_validation :generate_slug
-
-    private
-
-    def generate_slug
-      self.slug ||= name&.parameterize
-    end
-  end
-end
-```
-
-## Definitions
-
-### Post Definition
-
-```ruby
-module Blogging
-  class PostDefinition < Plutonium::Resource::Definition
-    # Form fields
-    field :title
-    field :slug, hint: "URL-friendly version (auto-generated if blank)"
-    field :body, as: :rich_text
-    field :excerpt, as: :text
-    field :category
-    field :tags, as: :select, multiple: true, collection: -> { Tag.pluck(:name, :id) }
-    field :featured_image, as: :file, accept: "image/*"
-    field :published, as: :switch
-    field :featured, as: :switch
-    field :meta_title
-    field :meta_description, as: :text
-
-    # Table columns
-    column :title, sortable: true
-    column :category
-    column :author
-    column :published
-    column :featured
-    column :published_at, sortable: true
-
-    # Search
-    search do |scope, query|
-      scope.where("title ILIKE :q OR body ILIKE :q", q: "%#{query}%")
-    end
-
-    # Scopes
-    scope :all, default: true
-    scope :published, -> { where(published: true) }, badge: true
-    scope :drafts, -> { where(published: false) }, badge: true
-    scope :featured, -> { where(featured: true) }
-
-    # Filters
-    filter :category, as: :select, collection: -> { Category.pluck(:name, :id) }
-    filter :author, as: :select, collection: -> { User.pluck(:name, :id) }
-    filter :published, as: :boolean
-    filter :created_at, as: :date_range
-
-    # Actions
-    action :publish, interaction: PublishPost, condition: ->(p) { !p.published? }
-    action :unpublish, interaction: UnpublishPost, condition: ->(p) { p.published? }
-    action :feature, interaction: FeaturePost, condition: ->(p) { !p.featured? }
-
-    # Associations
-    association :comments, fields: [:body, :author, :approved, :created_at]
-
-    # Eager loading
-    includes :author, :category, :tags
-  end
-end
-```
-
-### Comment Definition
-
-```ruby
-module Blogging
-  class CommentDefinition < Plutonium::Resource::Definition
-    field :body, as: :text
-    field :post, as: :hidden
-    field :author, as: :hidden
-    field :approved, as: :switch
-
-    column :body
-    column :author
-    column :approved
-    column :created_at
-
-    scope :all, default: true
-    scope :approved, -> { where(approved: true) }
-    scope :pending, -> { where(approved: false) }, badge: true
-
-    action :approve, interaction: ApproveComment, condition: ->(c) { !c.approved? }
-    action :reject, interaction: RejectComment, condition: ->(c) { c.approved? }
-  end
-end
-```
-
-## Interactions
-
-### Publish Post
-
-```ruby
-module Blogging
-  class PublishPost < Plutonium::Interaction::Base
-    presents model_class: Post
-    presents label: "Publish"
-    presents icon: Phlex::TablerIcons::Send
-
-    validate :has_content
-
-    def execute
-      resource.update!(
-        published: true,
-        published_at: Time.current
-      )
-
-      # Notify subscribers
-      NotifySubscribersJob.perform_later(resource.id)
-
-      succeed(resource).with_message("Post published!")
-    end
-
-    private
-
-    def has_content
-      errors.add(:base, "Post must have content") if resource.body.blank?
-    end
-  end
-end
-```
-
-### Approve Comment
-
-```ruby
-module Blogging
-  class ApproveComment < Plutonium::Interaction::Base
-    presents model_class: Comment
-    presents label: "Approve"
-
-    def execute
-      resource.update!(approved: true)
-
-      # Notify comment author
-      CommentApprovedMailer.notify(resource).deliver_later
-
-      succeed(resource).with_message("Comment approved")
-    end
-  end
-end
-```
-
-## Policies
-
-### Post Policy
-
-```ruby
-module Blogging
-  class PostPolicy < Plutonium::Resource::Policy
-    def read?
-      record.published? || author? || admin?
-    end
-
-    def create?
-      user.present? && (user.author? || user.admin?)
-    end
-
-    def update?
-      author? || admin?
-    end
-
-    def destroy?
-      author? || admin?
-    end
-
-    def publish?
-      (author? || admin?) && !record.published?
-    end
-
-    def relation_scope(relation)
-      if admin?
-        relation
-      elsif user&.author?
-        relation.where(author: user).or(relation.where(published: true))
-      else
-        relation.where(published: true)
-      end
-    end
-
-    private
-
-    def author?
-      record.author_id == user&.id
-    end
-
-    def admin?
-      user&.admin?
-    end
-  end
-end
-```
-
-## Portal Configuration
-
-### Admin Portal
-
-Engine:
-
-```ruby
-module AdminPortal
-  class Engine < Rails::Engine
-    include Plutonium::Portal::Engine
-  end
-end
-```
-
-Authentication (in controller concern):
-
-```ruby
-# packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb
-include Plutonium::Auth::Rodauth(:admin)
-```
-
-Admin policy override:
-
-```ruby
-# packages/admin_portal/app/policies/admin_portal/blogging/post_policy.rb
-module AdminPortal
-  module Blogging
-    class PostPolicy < ::Blogging::PostPolicy
-      def read?
-        true
-      end
-
-      def destroy?
-        true
-      end
-
-      def relation_scope(relation)
-        relation
-      end
-    end
-  end
-end
-```
-
-### Public Portal
-
-Engine:
-
-```ruby
-module PublicPortal
-  class Engine < Rails::Engine
-    include Plutonium::Portal::Engine
-  end
-end
-```
-
-Authentication (in controller concern):
-
-```ruby
-# packages/public_portal/app/controllers/public_portal/concerns/controller.rb
-include Plutonium::Auth::Rodauth(:user)
-```
-
-Public policy override:
-
-```ruby
-# packages/public_portal/app/policies/public_portal/blogging/post_policy.rb
-module PublicPortal
-  module Blogging
-    class PostPolicy < ::Blogging::PostPolicy
-      def create?
-        false
-      end
-
-      def update?
-        false
-      end
-
-      def relation_scope(relation)
-        relation.published
-      end
-    end
-  end
-end
-```
-
-## Usage
-
-```bash
-# Generate the structure
-rails generate pu:pkg:package blogging
-rails generate pu:res:scaffold Post title:string slug:string body:text published:boolean --dest=blogging
-rails generate pu:res:scaffold Comment body:text approved:boolean post:belongs_to --dest=blogging
-rails generate pu:res:scaffold Category name:string slug:string --dest=blogging
-
-# Create portals
-rails generate pu:pkg:portal admin
-rails generate pu:pkg:portal public
-
-# Connect resources to portal
-rails generate pu:res:conn Blogging::Post Blogging::Comment Blogging::Category --dest=admin_portal
-
-rails db:migrate
-```
-
-## Next Steps
-
-- Add image uploads with Active Storage
-- Implement RSS feeds
-- Add social sharing
-- Set up full-text search with PostgreSQL