plutonium 0.33.1 → 0.34.0

data/docs/modules/action.md

@@ -1,244 +0,0 @@
----
-title: Action Module
----
-
-# Action Module
-
-The Action module provides a comprehensive system for defining and managing custom actions in Plutonium applications. Actions represent operations that can be performed on resources, from simple navigation to complex business logic.
-
-::: tip
-The Action module is located in `lib/plutonium/action/`. Actions are typically defined within a resource's Definition file.
-:::
-
-## Overview
-
-- **Declarative Definition**: Define actions with metadata and behavior in your resource definition files.
-- **Multiple Action Types**: Support for actions on individual records, entire resources, or bulk collections.
-- **UI Integration**: Automatic button and form generation in the UI.
-- **Authorization Support**: Integrates with policies to control action visibility and execution.
-
-## Defining Actions
-
-Actions are typically defined in a resource definition file using the `action` method.
-
-```ruby
-# app/definitions/post_definition.rb
-class PostDefinition < Plutonium::Resource::Definition
-  # An action that runs a complex operation via an Interaction
-  action :publish,
-         interaction: PublishPostInteraction,
-         icon: Phlex::TablerIcons::Send,
-         category: :primary
-
-  # A simple navigation action
-  action :export,
-         route_options: { action: :export, format: :csv },
-         icon: Phlex::TablerIcons::Download,
-         resource_action: true # This is a resource-level action
-
-  # A destructive action with a confirmation
-  action :archive,
-         interaction: ArchivePostInteraction,
-         icon: Phlex::TablerIcons::Archive,
-         category: :danger,
-         confirmation: "Are you sure you want to archive this post?"
-end
-```
-
-### Action Types
-
-You can specify where an action should be available.
-
-::: code-group
-```ruby [Record Action]
-# Shows on the record's #show page and in the table row.
-action :edit,
-       record_action: true,
-       collection_record_action: true,
-       icon: Phlex::TablerIcons::Edit
-```
-```ruby [Resource Action]
-# Shows on the resource's #index page (e.g., "Import").
-action :import,
-       resource_action: true,
-       icon: Phlex::TablerIcons::Upload
-```
-```ruby [Bulk Action]
-# Appears when records are selected on the #index page.
-action :bulk_delete,
-       bulk_action: true,
-       category: :danger,
-       icon: Phlex::TablerIcons::Trash
-```
-:::
-
-### Action Categories & Positioning
-
-Categories and positioning control the visual appearance and order of action buttons.
-
-- **`category`**: Can be `:primary`, `:secondary`, or `:danger`.
-- **`position`**: A number used for sorting; lower numbers appear first (default: 50).
-
-```ruby
-# A prominent primary action
-action :create, category: :primary, position: 10
-
-# A standard secondary action
-action :archive, category: :secondary, position: 50
-
-# A destructive action, shown last
-action :delete, category: :danger, position: 100
-```
-
-## Action Types
-
-### Simple Actions
-
-Simple actions are for basic navigation or links. They are defined with `route_options`.
-
-::: code-group
-```ruby [Internal Link]
-# Navigates to the #reports action on the current controller
-action :view_reports,
-       label: "View Reports",
-       route_options: { action: :reports },
-       icon: Phlex::TablerIcons::ChartBar
-```
-```ruby [External Link]
-# Links to an external URL
-action :documentation,
-       label: "Documentation",
-       route_options: { url: "https://docs.example.com" },
-       icon: Phlex::TablerIcons::Book
-```
-:::
-
-### Dynamic Route Options
-
-For actions that need dynamic URL generation based on the current record or context, use the `RouteOptions` class with a custom `url_resolver`:
-
-::: code-group
-```ruby [Dynamic Parent-Child Navigation]
-# Navigate to create a child resource with the current record as parent
-action :create_deployment,
-       label: "Create Deployment",
-       icon: Phlex::TablerIcons::Rocket,
-       record_action: true,
-       route_options: Plutonium::Action::RouteOptions.new(
-         url_resolver: ->(subject) {
-           resource_url_for(UniversalFlow::Deployment, action: :new, parent: subject)
-         }
-       )
-```
-```ruby [Conditional Routing]
-# Different routes based on user permissions or record state
-action :manage_settings,
-       label: "Manage Settings",
-       resource_action: true,
-       route_options: Plutonium::Action::RouteOptions.new(
-         url_resolver: ->(subject) {
-           if current_user.admin?
-             admin_settings_path(subject)
-           else
-             basic_settings_path(subject)
-           end
-         }
-       )
-```
-```ruby [External Integration]
-# Dynamic external URLs based on record attributes
-action :view_external,
-       label: "View in External System",
-       record_action: true,
-       route_options: Plutonium::Action::RouteOptions.new(
-         url_resolver: ->(subject) {
-           "https://external-system.com/items/#{subject.external_id}"
-         }
-       )
-```
-:::
-
-The `url_resolver` lambda receives the current record (for record actions) or resource class (for resource actions) as the `subject` parameter, allowing you to generate URLs dynamically based on the context.
-
-### Interactive Actions
-
-Interactive actions are powered by an `Interaction` class and handle business logic. The action's properties (label, description, etc.) are often inferred from the interaction itself.
-
-```ruby
-# The action is automatically configured based on the interaction
-action :publish,
-       interaction: PublishPostInteraction,
-       icon: Phlex::TablerIcons::Send
-```
-
-::: details Automatic Type Detection from Interaction
-The Action module inspects the interaction's attributes to determine its type (`record`, `resource`, or `bulk`).
-```ruby
-# This will be a RECORD action because it has a `:resource` attribute.
-class PublishPostInteraction < Plutonium::Interaction::Base
-  attribute :resource
-  attribute :publish_date, :date
-end
-
-# This will be a BULK action because it has a `:resources` attribute.
-class BulkArchiveInteraction < Plutonium::Interaction::Base
-  attribute :resources
-  attribute :archive_reason, :string
-end
-
-# This will be a RESOURCE action because it has neither.
-class ImportPostsInteraction < Plutonium::Interaction::Base
-  attribute :csv_file, :string
-end
-```
-:::
-
-::: details Immediate vs. Modal Actions
-- If an interaction has **only** a `resource` or `resources` attribute, the action will execute immediately on click.
-- If it has **any other attributes**, a modal form will be rendered to collect user input before execution.
-```ruby
-# IMMEDIATE: No extra inputs, runs on click.
-class SimplePublishInteraction < Plutonium::Interaction::Base
-  attribute :resource
-end
-
-# MODAL: Requires `publish_date`, so a form will be shown.
-class ScheduledPublishInteraction < Plutonium::Interaction::Base
-  attribute :resource
-  attribute :publish_date, :datetime
-end
-```
-:::
-
-## Best Practices
-
-### Action Design
-
-1. **Clear Intent**: Use descriptive action names that clearly indicate what they do
-2. **Consistent Categories**: Group related actions using consistent categories
-3. **Appropriate Icons**: Choose icons that clearly represent the action
-4. **Meaningful Confirmations**: Use confirmation messages for destructive actions
-5. **Logical Positioning**: Order actions by importance and frequency of use
-
-### Dynamic Route Actions
-
-1. **Context Awareness**: Use the subject parameter to make routing decisions based on the current record or resource
-2. **Error Handling**: Handle cases where dynamic URLs might fail (e.g., missing external IDs)
-3. **Performance**: Keep url_resolver lambdas simple to avoid performance issues
-4. **Security**: Validate permissions within the lambda when generating sensitive URLs
-
-### Interactive Actions
-
-1. **Single Purpose**: Each action should have a single, well-defined purpose
-2. **Input Validation**: Always validate user inputs in the interaction
-3. **Error Messages**: Provide clear, actionable error messages
-4. **Success Feedback**: Give users clear feedback when actions complete successfully
-5. **Idempotency**: Design actions to be safely repeatable when possible
-
-### Security
-
-1. **Authorization**: Always check user permissions before executing actions
-2. **Input Sanitization**: Sanitize all user inputs
-3. **CSRF Protection**: Include CSRF tokens in all action forms
-4. **Rate Limiting**: Implement rate limiting for resource-intensive actions
-5. **Audit Logging**: Log important actions for security auditing

data/docs/modules/authentication.md

@@ -1,236 +0,0 @@
----
-title: Authentication Module
----
-
-# Authentication Module
-
-The Authentication module provides comprehensive authentication capabilities for Plutonium applications. It integrates seamlessly with Rodauth for authentication while offering flexibility for different application security needs.
-
-::: tip
-The Authentication module is located in `lib/plutonium/auth/`.
-:::
-
-## Overview
-
-- **Rodauth Integration**: Seamless integration with Rodauth authentication
-- **Public Access Support**: Optional public access for applications without authentication
-- **Multi-Account Support**: Support for multiple user types and authentication contexts
-- **Portal-Aware Security**: Authentication scoped to specific portals/packages
-- **Flexible Configuration**: Support for custom authentication systems
-- **Security Features**: Built-in security best practices and configurations
-
-## Core Components
-
-::: code-group
-```ruby [Rodauth Integration]
-# lib/plutonium/auth/rodauth.rb
-# Basic Rodauth integration
-module MyApp
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Auth::Rodauth(:main)
-
-      # Automatically provides:
-      # - current_user helper method
-      # - logout_url helper method
-      # - Proper URL options handling
-    end
-  end
-end
-```
-
-```ruby [Public Access]
-# For applications that don't require authentication
-module MyApp
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Auth::Public
-    end
-  end
-end
-```
-
-```ruby [Custom Authentication]
-# For applications using custom authentication systems
-module MyApp
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-
-      included do
-        helper_method :current_user
-      end
-
-      def current_user
-        # Your custom authentication logic
-        @current_user ||= User.find(session[:user_id]) if session[:user_id]
-      end
-    end
-  end
-end
-```
-:::
-
-### Automatic Helper Methods
-
-When you include `Plutonium::Auth::Rodauth`, you automatically get:
-
-- `current_user`: Returns the authenticated user/account (available in controllers and views).
-- `logout_url`: Returns the logout URL for the current account type (available in controllers and views).
-- `rodauth`: Access to the Rodauth instance (available in controllers only).
-
-## Rodauth Configuration
-
-### Account Generation
-
-Plutonium provides generators for creating Rodauth accounts:
-
-::: code-group
-```bash [Basic User Account]
-rails generate pu:rodauth:account user
-```
-
-```bash [Admin Account]
-rails generate pu:rodauth:admin admin
-```
-
-```bash [Custom Features]
-rails generate pu:rodauth:account customer \
-  --no-defaults \
-  --login --logout --create-account --verify-account \
-  --reset-password --change-password --remember
-```
-:::
-
-### Configuration Examples
-
-::: details Standard Rodauth Plugin Configuration
-```ruby
-# app/rodauth/user_rodauth_plugin.rb
-class UserRodauthPlugin < RodauthPlugin
-  configure do
-    # Enable features
-    enable :login, :logout, :create_account, :verify_account,
-           :reset_password, :change_password, :remember
-
-    # Account model
-    rails_account_model { User }
-
-    # Controller for views and CSRF
-    rails_controller { Rodauth::UserController }
-
-    # Redirects
-    login_redirect "/"
-    logout_redirect "/"
-    create_account_redirect "/"
-
-    # Email configuration
-    create_reset_password_email do
-      UserMailer.reset_password(account_id, reset_password_key_value)
-    end
-
-    # Remember feature
-    after_login { remember_login }
-    extend_remember_deadline? true
-
-    # Password requirements
-    password_minimum_length 8
-
-    # Custom validation
-    before_create_account do
-      throw_error_status(422, "name", "must be present") if param("name").empty?
-    end
-  end
-end
-```
-:::
-
-::: details Enhanced Admin Configuration with MFA
-```ruby
-# app/rodauth/admin_rodauth_plugin.rb
-class AdminRodauthPlugin < RodauthPlugin
-  configure do
-    enable :login, :logout, :create_account, :verify_account,
-           :reset_password, :change_password, :remember,
-           :otp, :recovery_codes, :lockout, :active_sessions,
-           :audit_logging, :password_grace_period, :internal_request
-
-    # Account model
-    rails_account_model { Admin }
-
-    # Controller
-    rails_controller { Rodauth::AdminController }
-
-    # Prefix for admin routes
-    prefix "/admin"
-
-    # Require MFA setup
-    two_factor_not_setup_error_flash "You need to setup two factor authentication"
-    two_factor_auth_return_to_requested_location? true
-
-    # Multi-phase login for enhanced security
-    use_multi_phase_login? true
-
-    # Prevent web signup for admin accounts
-    before_create_account_route do
-      request.halt unless internal_request?
-    end
-
-    # Enhanced security settings
-    max_invalid_logins 3
-    lockout_deadline_interval Hash[minutes: 60]
-
-    # Session security
-    session_key "_admin_session"
-    remember_cookie_key "_admin_remember"
-  end
-end
-```
-:::
-
-## Portal Integration
-
-Each portal can have its own authentication requirements, allowing you to secure different parts of your application with different user types.
-
-::: code-group
-```ruby [Admin Portal]
-# Admin portal with admin authentication
-module AdminPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-      include Plutonium::Auth::Rodauth(:admin)
-    end
-  end
-end
-```
-
-```ruby [Customer Portal]
-# Customer portal with customer authentication
-module CustomerPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-      include Plutonium::Auth::Rodauth(:customer)
-    end
-  end
-end
-```
-
-```ruby [Public Portal]
-# Public portal without authentication
-module PublicPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-      include Plutonium::Auth::Public
-    end
-  end
-end
-```
-:::