plutonium 0.23.4 → 0.23.5

data/docs/guide/tutorial/04-creating-a-portal.md

@@ -0,0 +1,101 @@
+# 4. Creating a Portal
+
+We have our `Blogging` feature package with `Post` and `Comment` resources, but no user interface to manage them. Let's create a **Portal** to serve as a web interface for our blog.
+
+## What are Portal Packages?
+
+While Feature Packages hold business logic, **Portal Packages** provide the web interface. They are also Rails Engines, but they are responsible for things like:
+
+- Dashboards and layouts.
+- Routing requests to the correct resources.
+- Handling user authentication for the interface.
+
+We'll create a `Dashboard` portal for managing our blog.
+
+## Generate the Portal
+
+Plutonium has a generator for portals. In your terminal, run:
+
+```bash
+rails generate pu:pkg:portal dashboard
+```
+
+The generator will ask which authentication account to use. We already set up the `user` account with Rodauth, so **select `user`**.
+
+This creates a new package at `packages/dashboard_portal/` and wires it up for authentication.
+
+## Connect Resources to the Portal
+
+Now we need to tell our new `Dashboard` portal which resources it should manage. We can use the `pu:res:conn` (connect) generator for this.
+
+Run the connect generator:
+```bash
+rails generate pu:res:conn
+```
+
+It will ask you a series of questions:
+1.  **Select source feature**: Choose **`blogging`**.
+2.  **Select resources**: Use the spacebar to select both **`Blogging::Post`** and **`Blogging::Comment`**, then press Enter.
+3.  **Select destination portal**: Choose **`dashboard_portal`**.
+
+This command does the magic of connecting your feature logic to your UI. It updates the portal's routes file (`packages/dashboard_portal/config/routes.rb`) to register the resources:
+
+```ruby
+# packages/dashboard_portal/config/routes.rb
+DashboardPortal::Engine.routes.draw do
+  root to: "dashboard#index"
+
+  register_resource Blogging::Post
+  register_resource Blogging::Comment
+end
+```
+
+## Configure Application Routes
+
+There's one last step. We need to tell our main Rails application how to handle routing for authentication and the new dashboard.
+
+1.  **Update Rodauth Redirects**: We want users to be sent to the dashboard after they log in or sign up.
+
+    ```ruby [app/rodauth/user_rodauth_plugin.rb]
+    # ==> Redirects
+
+    # Redirect to home after login.
+    create_account_redirect "/" # [!code --]
+    create_account_redirect "/dashboard" # [!code ++]
+
+    # Redirect to home after login.
+    login_redirect "/" # [!code --]
+    login_redirect "/dashboard" # [!code ++]
+
+    # Redirect to home page after logout.
+    logout_redirect "/" # [!code --]
+    logout_redirect "/dashboard" # [!code ++]
+    ```
+
+2.  **Update Root Route**: We'll make the dashboard the root of our application.
+
+    ```ruby [config/routes.rb]
+    Rails.application.routes.draw do
+      # ...
+      # Defines the root path route ("/")
+      # root "posts#index" # [!code --]
+      root to: redirect("/dashboard") # [!code ++]
+    end
+    ```
+
+## See it in Action!
+
+Let's check our progress. Start your Rails server (`rails s`) and navigate to [http://localhost:3000](http://localhost:3000).
+
+You will be redirected to `/dashboard` and should see the login page.
+
+- **Sign up** for a new account.
+- After signing up, you'll be redirected to the dashboard. It will be empty for now, but this confirms the portal and authentication are working!
+
+![Plutonium Empty Dashboard](/tutorial/plutonium-posts-dashboard.png)
+
+## Next Steps
+
+We now have a functional dashboard! It's not very useful yet, though.
+
+In the next chapter, we will customize the user interface to display our posts and comments, and add navigation to make them accessible.

data/docs/guide/tutorial/05-customizing-the-ui.md

@@ -0,0 +1,128 @@
+# 5. Customizing the UI
+
+Our dashboard is functional, but it's not very user-friendly. In Plutonium, customizing the UI is a two-step process that respects the separation of concerns:
+
+1.  **Policy (`app/policies`)**: The policy file controls **what** a user is authorized to see or edit. This is a security layer.
+2.  **Definition (`app/definitions`)**: The definition file controls **how** those permitted fields are displayed and formatted. This is a presentation layer.
+
+Let's customize our `Post` resource by following this two-step process for the table, detail page, and form.
+
+## Customizing the Posts Table (Index View)
+
+First, we'll define **what** columns should appear in the posts table. This is an authorization concern, so we'll use the policy file.
+
+Open the post policy: `packages/blogging/app/policies/blogging/post_policy.rb`
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # ... (other methods)
+
+  # 1. Define WHAT columns are visible in the table.
+  def permitted_attributes_for_index
+    [:user, :title, :published_at, :created_at]
+  end
+end
+```
+
+Next, we'll configure **how** these columns are displayed in the definition file.
+
+Open the post definition: `packages/blogging/app/definitions/blogging/post_definition.rb`
+
+```ruby
+# packages/blogging/app/definitions/blogging/post_definition.rb
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  # 2. Define HOW the permitted columns are rendered.
+  column :published_at, as: :datetime
+  column :created_at, as: :datetime
+end
+```
+
+The table now only shows the permitted columns, formatted as we specified.
+
+![Plutonium Posts Dashboard (Customized)](/tutorial/plutonium-posts-dashboard-customized.png)
+
+## Customizing the Post Detail Page (Show View)
+
+The same two-step process applies to the detail page.
+
+1.  **Policy**: Define what fields are visible with `permitted_attributes_for_show`.
+2.  **Definition**: Define how they are rendered with `display`.
+
+Let's define the fields in the policy. For this view, we want to show the `:content`.
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # ...
+
+  def permitted_attributes_for_index
+    [:user, :title, :published_at, :created_at]
+  end
+
+  # 1. Define WHAT fields are visible on the show page.
+  def permitted_attributes_for_show
+    [:user, :title, :content, :published_at, :created_at]
+  end
+end
+```
+
+Now, let's configure the layout in the definition. We'll make each field take up the full width of the view.
+
+```ruby
+# packages/blogging/app/definitions/blogging/post_definition.rb
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  display :user, wrapper: { class: "col-span-full" }
+  display :title, wrapper: { class: "col-span-full" }
+  display :content, wrapper: { class: "col-span-full" }
+  display :published_at, wrapper: { class: "col-span-full" }
+  display :created_at, wrapper: { class: "col-span-full" }
+end
+```
+
+![Plutonium Posts Detail (Customized)](/tutorial/plutonium-posts-detail-customized.png)
+
+## Customizing the Post Form
+
+Finally, we'll customize the `new` and `edit` forms.
+
+1.  **Policy**: Use `permitted_attributes_for_create` and `_for_update` to control which fields can be submitted.
+2.  **Definition**: Use the `input` helper to control how the form inputs are rendered.
+
+First, the policy. We don't want the user to be able to set the `published_at` date directly in the form.
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # ...
+
+  # 1. Define WHAT fields can be submitted in the form.
+  def permitted_attributes_for_create
+    [:user_id, :title, :content]
+  end
+
+  def permitted_attributes_for_update
+    permitted_attributes_for_create
+  end
+end
+```
+
+Now, the definition. We'll use the `input` helper to specify that `:content` should use a rich text editor.
+
+```ruby
+# packages/blogging/app/definitions/blogging/post_definition.rb
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  # ... (display helpers from above)
+
+  # 2. Define HOW the form inputs are rendered.
+  input :content, as: :rich_text # Use a rich text editor
+end
+```
+
+By separating what is permitted from how it is rendered, Plutonium gives you both security and flexibility.
+
+## Next Steps
+
+Our UI is now much more polished. We've used the **Policy** and **Definition** files together to customize our `Post` resource.
+
+In the next chapter, we'll add custom business logic by creating an **Action** to publish a draft post.

data/docs/guide/tutorial/06-adding-custom-actions.md

@@ -0,0 +1,101 @@
+# 6. Adding Custom Actions
+
+Our application now handles the basics of creating, reading, updating, and deleting posts and comments. But what about business logic that isn't simple CRUD? For this, Plutonium has **Actions**.
+
+An Action is a piece of business logic you can execute on a resource. We'll create a "Publish" action for our posts.
+
+Create a new file for our "interaction" at:
+`packages/blogging/app/interactions/blogging/post_interactions/publish.rb`
+
+## Implement the Interaction
+
+The "Interaction" is where the business logic for an action lives. Open the newly created file and let's implement the logic to publish a post.
+
+We want the action to set the `published_at` timestamp on the post.
+
+```ruby
+# packages/blogging/app/interactions/blogging/post_interactions/publish.rb
+module Blogging
+  module PostInteractions
+    class Publish < Plutonium::Resource::Interaction
+      # Define the attributes this interaction accepts
+      attribute :resource, class: "Blogging::Post"
+
+      # Define how this action is presented in the UI
+      presents label: "Publish Post",
+               description: "Make this post available for the public to see."
+
+      private
+
+      # The core business logic
+      def execute
+        if resource.update(published_at: Time.current )
+          succeed(resource)
+            .with_message("Post was successfully published.")
+            .with_redirect_response(resource)
+        else
+          failed(resource.errors)
+        end
+      end
+    end
+  end
+end
+```
+
+This class defines what the action needs (`resource`, `published_at`), how it looks (`presents`), and what it does (`execute`).
+
+## Configure the Action
+
+Now that we've defined the logic, we need to add the action to our `Post` resource and configure its visibility. We'll do this in the post's **definition** file.
+
+`packages/blogging/app/definitions/blogging/post_definition.rb`
+
+Add the `action` configuration:
+
+```ruby
+# packages/blogging/app/definitions/blogging/post_definition.rb
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  # ... (display helpers from the previous chapter)
+
+  action :publish,
+    interaction: "Blogging::PostInteractions::Publish"
+end
+```
+
+## Control Visibility with a Policy
+
+Plutonium actions are secure by default. If an action doesn't have a corresponding policy method allowing it, it won't be displayed.
+
+Let's define the logic for our `publish` action. We only want to show the "Publish" button if the post hasn't been published yet.
+
+Open the post policy file:
+`packages/blogging/app/policies/blogging/post_policy.rb`
+
+Add the `publish?` method:
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # ... (other methods from previous chapters)
+
+  def publish?
+    # Only allow publishing if the user can update the post
+    # and the post has not been published yet.
+    update? && record.published_at.nil?
+  end
+end
+```
+
+This policy does two things:
+1. It ensures the user has permission to `update?` the post.
+2. It checks that `published_at` is `nil`.
+
+Now, go to the show page for a post you created. You should see the "Publish" button. Click it, and the `published_at` field will be set. Because `record.published_at.nil?` is now false, the policy will prevent the action from being shown again. The button disappears!
+
+![Plutonium Posts Publish Action](/tutorial/plutonium-publish-post.png)
+
+## Next Steps
+
+We've successfully added custom business logic to our application. Actions are a powerful way to build complex, maintainable features.
+
+In the final chapter of this tutorial, we'll tighten up security by implementing proper authorization rules.

data/docs/guide/tutorial/07-implementing-authorization.md

@@ -0,0 +1,90 @@
+# 7. Implementing Authorization
+
+Our blog is now fully functional, but it's not very secure. Any user can edit or delete any other user's posts. Let's fix this by implementing proper authorization rules using Plutonium's **Policy** system.
+
+## Understanding Policies
+
+For every resource, there is a corresponding Policy class that controls access. The policy methods (like `update?` or `destroy?`) return `true` or `false` to grant or deny permission.
+
+## Securing Post Actions
+
+Let's start by restricting the `update` and `publish` actions for posts. Open the post policy file:
+
+`packages/blogging/app/policies/blogging/post_policy.rb`
+
+Now, let's modify the policy to check if the current user (`user`) is the owner of the post (`record`).
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # Users can only update their own posts
+  def update?
+    record.user_id == user.id
+  end
+
+  # Only the owner can publish their post
+  def publish?
+    update? # Inherits from update?
+  end
+end
+```
+By default, `destroy?` also inherits from `update?`, so this one change secures all write operations.
+
+## Securing Comment Actions
+
+We should apply the same logic to comments. Open the comment policy:
+
+`packages/blogging/app/policies/blogging/comment_policy.rb`
+
+And add the same ownership check:
+
+```ruby
+# packages/blogging/app/policies/blogging/comment_policy.rb
+class Blogging::CommentPolicy < Blogging::ResourcePolicy
+  def update?
+    record.user_id == user.id
+  end
+end
+```
+
+## Scoping Visible Data
+
+We've secured the actions, but there's one more problem: every user can see every post in the index view. We should scope the list of posts so that users only see their own.
+
+This is done with the `relation_scope` in the post policy file. This scope is applied to all queries for the `Post` resource.
+
+`packages/blogging/app/policies/blogging/post_policy.rb`
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # ... (update? and publish? methods)
+
+  # Scope all queries to only include the current user's posts
+  relation_scope do |scope|
+    scope.where(user: user)
+  end
+end
+```
+Now, the posts index page will only show posts created by the currently logged-in user. This is a critical feature for multi-tenant applications.
+
+## Tutorial Complete!
+
+Congratulations! You have built a complete, secure, and modular blog application with Plutonium.
+
+You've learned how to:
+- Set up a Plutonium project.
+- Organize features into **Packages**.
+- Define and scaffold **Resources**.
+- Build a web interface with **Portals**.
+- Customize the UI.
+- Add custom business logic with **Actions**.
+- Secure your application with **Policies**.
+
+### Where to Go Next?
+
+You now have a strong foundation to build your own applications. To learn more about specific topics, check out our **Deep Dive Guides**:
+
+- **[Resources](./../deep-dive/resources.md)**: An in-depth look at fields, associations, filters, and more.
+- **[Authorization](./../deep-dive/authorization.md)**: A detailed guide to policies, scopes, and entity-based authorization.
+- ... more guides coming soon!

data/docs/index.md

@@ -3,45 +3,38 @@
 layout: home
 
 hero:
-  name: Plutonium RADKit
-  tagline: The Ultimate Rapid Application Development Toolkit (RADKit) for Rails
+  name: Plutonium
+  text: The Rails RAD Toolkit
+  tagline: Build feature-rich, enterprise-ready applications at lightning speed. Stop writing boilerplate, start building features.
   image:
     src: /plutonium.png
     alt: Plutonium
   actions:
     - theme: brand
-      text: Get started
-      link: /guide/getting-started/
+      text: Start the Tutorial
+      link: /guide/tutorial/01-project-setup
     - theme: alt
-      text: Learn more
-      link: /guide/what-is-plutonium
+      text: Core Concepts
+      link: /guide/introduction/02-core-concepts
 
 features:
-  # Core Value Proposition - Start with the main benefit
-  - title: Rich Resource Management
-    details: Beautiful, modern interfaces with production-ready components for rapid development
+  - icon: 🚀
+    title: Unmatched Developer Experience
+    details: Smart generators, convention-over-configuration, and intelligent defaults let you focus on what matters.
+  - icon: 🏗️
+    title: Robust Architecture
+    details: Built-in multitenancy, modular packages, and advanced authorization provide a solid foundation for any project.
+  - icon: 🎨
+    title: Flexible UI & Theming
+    details: Start with a beautiful, modern UI out-of-the-box, then customize any aspect with a powerful and expressive API.
 
-  # Core Architecture Features - Foundation pieces
-  - title: Built-in Multitenancy
-    details: Row-level multitenancy that works out of the box - perfect for SaaS and enterprise apps
-
-  - title: Advanced Authorization
-    details: Comprehensive access control built on Action Policy's proven authorization framework
-
-  - title: Seamless Authentication
-    details: Integrate your existing auth or use our Rodauth integration - ready in seconds
-
-  # Developer Experience Features - How it makes development easier
-  - title: Intelligent Fields
-    details: Smart field detection with automatic Rails model mapping and zero configuration needed
-
-  - title: Advanced Nested Resources
-    details: Complex resource relationships made simple through intelligent relationship mapping
+---
 
-  # Extensibility Features - How it grows with your needs
-  - title: Extensible Workflows
-    details: Add custom actions and business workflows with a simple, declarative API
+<style>
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #da8ee7 30%, #5f4dff);
 
-  - title: Flexible UI Customization
-    details: Customize any aspect of your interfaces with elegant builder APIs
----
+  --vp-home-hero-image-filter: blur(56px);
+}
+</style>

data/docs/modules/action.md

@@ -0,0 +1,190 @@
+---
+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
+```
+:::
+
+### 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
+
+### 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