plutonium 0.15.5 → 0.15.7

data/docs/guide/getting-started/core-concepts.md

@@ -0,0 +1,432 @@
+# Core Concepts
+
+::: tip What you'll learn
+- Understanding Plutonium's architecture and core abstractions
+- How resources and packages work together
+- How to organize your application effectively
+- Best practices for building maintainable applications
+:::
+
+## Resources
+
+Resources are the fundamental building blocks of a Plutonium application. They represent your business domain objects and their associated behavior.
+
+### Anatomy of a Resource
+
+A resource consists of several interconnected components:
+
+```mermaid
+graph TD
+    A[Resource] --> B[Model]
+    A --> C[Definition]
+    A --> D[Policy]
+    A --> G[Actions]
+
+    B --> H[Database Schema]
+    C --> I[Fields & UI Logic]
+    C --> F[QueryObject]
+    D --> J[Authorization]
+    F --> L[Querying & Filtering]
+    G --> M[User Operations]
+```
+
+::: details Complete Resource Example
+
+::: code-group
+```ruby [Model]
+# app/models/user.rb
+class User < ApplicationRecord
+  include Plutonium::Resource::Record
+
+  # Associations
+  has_many :posts
+  has_many :comments
+  belongs_to :organization
+
+  # Scopes
+  scope :active, -> { where(status: :active) }
+
+  # Validations
+  validates :name, presence: true
+  validates :email, presence: true, uniqueness: true
+  validates :role, presence: true, inclusion: {in: %w[admin user]}
+
+  def admin? = role == "admin"
+end
+```
+
+```ruby [Definition]
+# app/definitions/user_definition.rb
+class UserDefinition < Plutonium::Resource::Definition
+  # Display configuration
+  field :name, as: :string
+  field :email, as: :email
+
+  # Search configuration
+  search do |scope, query|
+    scope.where("name LIKE :q OR email LIKE :q", q: "%#{query}%")
+  end
+
+  # Filters
+  filter :role, with: SelectFilter, choices: %w[admin user guest]
+  filter :status, with: SelectFilter, choices: %w[active inactive]
+
+  # Scopes
+  scope :active
+
+  scope :admins do
+    where(role: :admin)
+  end
+
+  # Actions
+  action :deactivate,
+    interaction: DeactivateUser,
+    color: :warning,
+    icon: Phlex::TablerIcons::UserOff
+
+  # UI Customization
+  show_page_title "User Details"
+  show_page_description "View and manage user information"
+end
+```
+
+```ruby [Policy]
+# app/policies/user_policy.rb
+class UserPolicy < Plutonium::Resource::Policy
+  # Basic permissions
+  def read?
+    true
+  end
+
+  def create?
+    user.admin?
+  end
+
+  def update?
+    user.admin? || record.id == user.id
+  end
+
+  def destroy?
+    user.admin? && record.id != user.id
+  end
+
+  # Action permissions
+  def deactivate?
+    user.admin? && record.status == :active && record.id != user.id
+  end
+
+  # Attribute permissions
+  def permitted_attributes_for_read
+    if user.admin?
+      %i[name email role status created_at updated_at]
+    else
+      %i[name email status]
+    end
+  end
+
+  def permitted_attributes_for_create
+    if user.admin?
+      %i[name email role status password]
+    else
+      %i[name email password]
+    end
+  end
+
+  def permitted_attributes_for_update
+    if user.admin?
+      %i[name email role]
+    else
+      %i[name email]
+    end
+  end
+
+  # Association permissions
+  def permitted_associations
+    %i[posts comments]
+  end
+end
+```
+
+
+```ruby [Deactivate Interaction]
+# app/interactions/user_interactions/deactivate.rb
+module UserInteractions
+  class Deactivate < Plutonium::Resource::Interaction
+    # Define presentable metadata
+    presents label: "Deactivate User",
+             icon: Phlex::TablerIcons::UserOff,
+             description: "Deactivate user account"
+
+    # Define attributes
+    attribute :resource, class: User
+    attribute :reason, :string
+
+    # Validations
+    validates :resource, presence: true
+    validates :reason, presence: true
+
+    # Business logic
+    def execute
+      resource.transaction do
+        resource.status = :inactive
+        resource.deactivated_at = Time.current
+        resource.deactivation_reason = reason
+
+        if resource.save
+          succeed(resource)
+            .with_message("User was successfully deactivated")
+            .with_redirect_response(resource)
+        else
+          failed(resource.errors)
+        end
+      end
+    end
+  end
+end
+```
+:::
+
+## Packages
+
+Packages are the way Plutonium helps you modularize your application. They're built on top of Rails Engines but provide additional structure and conventions.
+
+There are two main types:
+
+### Feature Packages
+
+
+Feature packages help you organize your application into logical, reusable modules.
+They contain your business domain logic and resources. They're self-contained and independent.
+
+::: tip Key Characteristics
+- Domain Models
+- Business Logic
+- No Web Interface
+- Reusable Components
+:::
+
+::: code-group
+```ruby [Directory Structure]
+packages/
+└── blogging/
+    ├── app/
+    │   ├── models/
+    │   │   └── blogging/
+    │   │       ├── post.rb
+    │   │       └── comment.rb
+    │   ├── definitions/
+    │   │   └── blogging/
+    │   │       ├── post_definition.rb
+    │   │       └── comment_definition.rb
+    │   ├── policies/
+    │   │   └── blogging/
+    │   │       ├── post_policy.rb
+    │   │       └── comment_policy.rb
+    │   └── interactions/
+    │       └── blogging/
+    │           └── post_interactions/
+    │               ├── publish.rb
+    │               └── archive.rb
+    ├── config/
+    │   └── routes.rb
+    └── lib/
+        └── engine.rb
+```
+
+```ruby [Engine Configuration]
+# packages/blogging/lib/engine.rb
+module Blogging
+  class Engine < ::Rails::Engine
+    include Plutonium::Package::Engine
+
+    # Package configuration goes here
+    isolate_namespace Blogging
+  end
+end
+```
+:::
+
+### Portal Packages
+
+Portal packages provide web interfaces and control how users interact with features.
+
+::: tip Key Characteristics
+- Web Interface
+- Authentication
+- Resource Access Control
+- Feature Composition
+:::
+
+::: code-group
+```ruby [Directory Structure]
+packages/
+└── admin_portal/
+    ├── app/
+    │   ├── controllers/
+    │   │   └── admin_portal/
+    │   │       ├── concerns/
+    │   │       │   └── controller.rb
+    │   │       ├── plutonium_controller.rb
+    │   │       └── resource_controller.rb
+    │   └── views/
+    │       └── layouts/
+    │           └── admin_portal.html.erb
+    ├── config/
+    │   └── routes.rb
+    └── lib/
+        └── engine.rb
+```
+
+```ruby [Engine Configuration]
+# packages/admin_portal/lib/engine.rb
+module AdminPortal
+  class Engine < ::Rails::Engine
+    include Plutonium::Portal::Engine
+
+    # Scope all resources to organization
+    scope_to_entity Organization, strategy: :path
+  end
+end
+```
+
+```ruby [Routes Configuration]
+# packages/admin_portal/config/routes.rb
+AdminPortal::Engine.routes.draw do
+  root to: "dashboard#index"
+
+  # Register resources from feature packages
+  register_resource Blogging::Post
+  register_resource Blogging::Comment
+end
+```
+
+```ruby [Controller Configuration]
+# packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb
+module AdminPortal
+  module Concerns
+    class Controller < ::Rails::Engine
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+      # Integrate authentication
+      include Plutonium::Auth::Rodauth(:admin)
+    end
+  end
+end
+```
+:::
+
+## Entity Scoping
+
+Entity scoping is a powerful feature that allows you to partition resources based on a parent entity (like Organization or Account).
+It's how Plutonium achieve's multitenancy.
+
+By properly defining associations to an entity, row-level multitenancy comes for free, out of the box.
+
+```ruby
+# Scope definition in engine
+module AdminPortal
+  class Engine < ::Rails::Engine
+    include Plutonium::Portal::Engine
+
+    # Path-based scoping (/org_123/posts)
+    scope_to_entity Organization, strategy: :path
+
+    # Or custom scoping
+    scope_to_entity Organization, strategy: :current_organization
+  end
+end
+
+# Model implementation
+class Post < ApplicationRecord
+  include Plutonium::Resource::Record
+
+  # Define a direct relationship to the entity
+  belongs_to :user
+  belongs_to :organization, through: :user
+
+  # Alternatively, if there's no direct relationship
+  scope :associated_with_organization, ->(organization) do
+    # custom scoping logic goes here
+    joins(:user).where(users: { organization_id: organization.id })
+  end
+end
+
+# Controller config
+class ResourceController < PlutoniumController
+  include Plutonium::Resource::Controller
+
+  private
+
+  def current_organization
+    # Get tenant from the current subdomain
+    @current_organization ||= Organization.where(subdomain: request.subdomain).first!
+  end
+end
+```
+
+## Best Practices
+
+### Package Organization
+
+::: tip Feature Packages
+1. Keep domain logic isolated
+2. Clear boundaries between features
+3. Minimal dependencies between packages
+4. Well-defined interfaces
+:::
+
+::: tip Portal Packages
+1. Single responsibility (admin, customer)
+2. Consistent authentication strategy
+3. Clear resource scoping rules
+4. Feature composition over duplication
+:::
+
+### Resource Design
+
+::: tip Model Layer
+1. Clear validations and constraints
+2. Proper association setup
+3. Meaningful scopes
+:::
+
+::: tip Definition Layer
+1. Appropriate field types
+2. Clear action definitions
+3. Efficient search implementation
+:::
+
+::: tip Policy Layer
+1. Granular permissions
+2. Attribute-level access control
+3. Action-specific rules
+4. Association permissions
+:::
+
+### Security Considerations
+
+::: warning Important
+1. Always implement proper policies
+2. Use entity scoping consistently
+3. Validate all inputs
+4. Control association access
+5. Audit sensitive actions
+:::
+
+## Generator Support
+
+Plutonium provides generators to quickly scaffold components:
+
+```bash
+# Create a new feature package
+rails generate pu:pkg:package blogging
+
+# Create a new portal package
+rails generate pu:pkg:portal admin
+
+# Create a new resource
+rails generate pu:res:scaffold post title:string content:text
+
+# Connect a resource to a portal
+rails generate pu:res:conn
+```

data/docs/guide/getting-started/index.md

@@ -0,0 +1,18 @@
+# Getting Started with Plutonium
+
+<!--
+This guide covers getting up and running with Plutonium.
+
+After reading this guide, you will know:
+
+- How to install Plutonium.
+- The general layout of a Plutonium application.
+- The basic principles of Resource design.
+- How to quickly generate the starting pieces of a Plutonium application.
+-->
+
+## Prerequisites
+
+Before using Plutonium, you should be familiar with Rails.
+Plutonium builds upon many core Rails concepts and conventions.
+If you're new to Rails or need a refresher, we highly recommend reading the [Rails' guide](https://guides.rubyonrails.org/getting_started.html).

data/docs/guide/getting-started/installation.md

@@ -0,0 +1,270 @@
+# Installation and Setup
+
+::: tip VERSION REQUIREMENTS
+- Ruby 3.2.2 or higher
+- Rails 7.1 or higher
+- Node.js and Yarn
+:::
+
+## Quick Start
+
+Get up and running with Plutonium in seconds:
+
+::: code-group
+```bash [New App]
+rails new plutonium_app -a propshaft -j esbuild -c tailwind \
+  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+```
+
+```bash [Existing App]
+bin/rails app:template \
+  LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
+```
+:::
+
+## Detailed Installation Guide
+
+1. Add Plutonium to your Gemfile:
+
+::: code-group
+```ruby [Gemfile]
+gem "plutonium"
+```
+
+```bash [Terminal]
+bundle install
+```
+:::
+
+2. Run the installation generator:
+
+```bash
+rails generate pu:core:install
+```
+
+This will:
+- Set up the basic Plutonium structure
+- Create necessary configuration files
+- Configure your application for Plutonium
+
+### Project Structure
+
+After installation, your project will have the following new directories and files:
+
+```
+my_rails_app/
+├── app/
+│   ├── controllers/
+│   │   ├── plutonium_controller.rb     # Base controller for Plutonium
+│   │   └── resource_controller.rb      # Base controller for resources
+│   ├── definitions/
+│   │   └── resource_definition.rb      # Base class for resource definitions
+│   ├── interactions/
+│   │   └── resource_interaction.rb     # Base class for resource interactions
+│   ├── models/
+│   │   └── resource_record.rb         # Base module for resource models
+│   ├── policies/
+│   │   └── resource_policy.rb         # Base class for resource policies
+│   └── views/
+│       └── layouts/
+│           └── resource.html.erb       # Base layout for resources
+├── config/
+│   ├── initializers/
+│   │   └── plutonium.rb               # Main configuration
+│   └── packages.rb                    # Package registration
+└── packages/                          # Directory for modular features
+    └── .keep
+```
+
+## Configuration
+
+### Basic Configuration
+
+Configure Plutonium in `config/initializers/plutonium.rb`:
+
+```ruby
+Plutonium.configure do |config|
+  # Load default configuration for version 1.0
+  config.load_defaults 1.0
+
+  # Asset configuration
+  config.assets.stylesheet = "plutonium.css" # Default stylesheet
+  config.assets.script = "plutonium.js"     # Default JavaScript
+  config.assets.logo = "plutonium.png"   # Default logo
+end
+```
+
+### Authentication Setup
+
+Plutonium supports multiple authentication strategies. Here's how to set up the recommended Rodauth integration:
+
+1. Install Rodauth:
+
+```bash
+rails generate pu:rodauth:install
+```
+
+2. Create an authentication account:
+
+::: code-group
+```bash [Basic Setup]
+rails generate pu:rodauth:account user
+```
+
+```bash [Custom Setup]
+# Include selected authentication features
+rails generate pu:rodauth:account admin --no-defaults \
+  --login --logout --remember --lockout \
+  --create-account --verify-account --close-account \
+   --change-password --reset-password --reset-password-notify \
+  --active-sessions --password-grace-period --otp \
+  --recovery-codes --audit-logging --internal-request
+```
+:::
+
+3. Configure the authentication controller:
+
+```ruby
+# app/controllers/resource_controller.rb
+class ResourceController < PlutoniumController
+  include Plutonium::Resource::Controller
+  include Plutonium::Auth::Rodauth(:user)
+end
+```
+
+::: tip
+You can use your existing authentication system by implementing the `current_user` method in `ResourceController`.
+:::
+
+<!--
+## Asset Pipeline Setup
+
+### JavaScript Setup
+
+
+Plutonium uses modern JavaScript features. Here's how to set it up:
+
+1. Install required npm packages:
+
+::: code-group
+```bash [importmap]
+bin/importmap pin @radioactive-labs/plutonium
+```
+
+```bash [esbuild]
+yarn add @radioactive-labs/plutonium
+```
+:::
+
+
+2. Configure JavaScript:
+
+::: code-group
+```js [app/javascript/controllers/index.js]
+import { application } from "controllers/application"
+import { registerControllers } from "@radioactive-labs/plutonium" // [!code ++]
+registerControllers(application) // [!code ++]
+```
+
+```js [app/javascript/application.js]
+import "@hotwired/turbo-rails"
+import "controllers"
+```
+:::
+
+### CSS Setup
+
+Plutonium uses Tailwind CSS. Configure it in your `tailwind.config.js`:
+
+```js
+const defaultTheme = require('tailwindcss/defaultTheme')
+
+module.exports = {
+  content: [
+    './app/views/**/*.erb',
+    './app/helpers/**/*.rb',
+    './app/javascript/**/*.js',
+    './app/components/**/*.{erb,rb}',
+    './node_modules/@radioactive-labs/plutonium/**/*.{js,ts}'
+  ],
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['Inter var', ...defaultTheme.fontFamily.sans],
+      },
+    },
+  },
+  plugins: [
+    require('@tailwindcss/forms'),
+    require('flowbite/plugin')
+  ],
+}
+```
+-->
+
+## Optional Enhancements
+
+### Database Performance
+
+For PostgreSQL/MySQL users, add these recommended gems:
+
+```ruby
+group :development, :test do
+  # N+1 query detection
+  gem "prosopite"
+end
+
+# Automatic eager loading
+gem "goldiloader"
+```
+
+### Development Tools
+
+Add helpful development gems:
+
+```ruby
+# Generate model annotations
+rails generate pu:gem:annotate
+
+# Set up environment variables
+rails generate pu:gem:dotenv
+```
+
+<!--
+## Verification
+
+Verify your installation:
+
+```bash
+# Start your Rails server
+rails server
+
+# Check your logs for any warnings or errors
+tail -f log/development.log
+
+# Generate and test a sample resource
+rails generate pu:res:scaffold Post title:string content:text
+```
+
+Visit `http://localhost:3000/posts` to verify everything is working.
+-->
+
+<!--
+::: tip Next Steps
+Now that you have Plutonium installed and configured, you're ready to:
+1. [Create your first resource](/guide/resources/creating-resources)
+2. [Set up your first package](/guide/packages/creating-packages)
+3. [Configure authorization](/guide/authorization/basic-setup)
+:::
+-->
+
+<!--
+### Getting Help
+
+If you run into issues:
+
+1. Check the [FAQ](/guide/faq)
+2. Search [GitHub Issues](https://github.com/radioactive-labs/plutonium-core/issues)
+3. Join our [Discord Community](https://discord.gg/plutonium)
+4. Create a new [GitHub Issue](https://github.com/radioactive-labs/plutonium-core/issues/new)
+-->