plutonium 0.15.7 → 0.15.9

data/docs/.vitepress/config.ts

@@ -26,6 +26,7 @@ export default defineConfig(withMermaid({
           text: "Introduction",
           items: [
             { text: "What is Plutonium?", link: "/guide/what-is-plutonium" },
+            { text: "Tutorial", link: "/guide/tutorial" },
           ]
         },
         {

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

@@ -1,7 +1,6 @@
 # Getting Started with Plutonium
 
 <!--
-This guide covers getting up and running with Plutonium.
 
 After reading this guide, you will know:
 
@@ -10,6 +9,10 @@ After reading this guide, you will know:
 - The basic principles of Resource design.
 - How to quickly generate the starting pieces of a Plutonium application.
 -->
+This guide covers getting up and running with Plutonium.
+It is intended to be a more detailed guide.
+
+If you're interested in a quick start, check out our [tutorial](/guide/tutorial).
 
 ## Prerequisites
 

data/docs/guide/tutorial.md

@@ -0,0 +1,403 @@
+# Building a Blog with Plutonium
+
+# Building a Blog with Plutonium
+
+> **Quick Links:**
+> - 🔍 [Tutorial Demo](https://github.com/radioactive-labs/plutonium-app)
+> - 📂 [Tutorial Source Code](https://github.com/radioactive-labs/plutonium-app)
+
+This tutorial walks through building a blog application using Plutonium. You'll learn how to:
+
+- Set up authentication using Rodauth
+- Create a blog feature package
+- Build a dashboard/portal
+- Implement posts and comments
+- Add interactive actions
+- Configure scoping and authorization
+
+[Rest of the tutorial content remains exactly the same...]
+
+## Initial Setup
+
+Let's start by creating a new Rails application with Plutonium:
+
+```bash
+rails new plutonium_app -a propshaft -j esbuild -c tailwind \
+  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+```
+
+This creates a new Rails application with:
+- Propshaft as the asset pipeline
+- esbuild for JavaScript bundling
+- Tailwind CSS for styling
+- Plutonium's base configuration
+
+## Setting Up Authentication
+
+Next, let's add authentication using Rodauth:
+
+```bash
+# Generate Rodauth configuration
+rails generate pu:rodauth:install
+
+# Generate user account setup
+rails generate pu:rodauth:account user
+rails db:migrate
+```
+
+This sets up:
+- A User model with authentication
+- Login/logout functionality
+- Account verification via email
+- Password reset capabilities
+
+![Plutonium Login Page](/tutorial/plutonium-login-page.png)
+
+The key files created include:
+- `app/models/user.rb` - The User model
+- `app/rodauth/user_rodauth_plugin.rb` - Rodauth configuration
+- `app/controllers/rodauth_controller.rb` - Base controller for auth pages
+- Database migrations for users and auth-related tables
+
+## Creating the Blog Feature Package
+
+Let's create a dedicated package for our blogging functionality:
+
+```bash
+rails generate pu:pkg:package blogging
+```
+
+This generates a new feature package under `packages/blogging/` with:
+- Base controllers
+- Model and policy base classes
+- Package-specific views directory
+- Engine configuration
+
+## Adding Posts Resource
+
+Now we can add our first resource - blog posts:
+
+```bash
+rails generate pu:res:scaffold post user:belongs_to title:string \
+  content:text 'published_at:datetime?'
+```
+
+::: tip
+Unlike Rails, Plutonium generates fields as non-null by default.
+Appending `?` to the type e.g. `published_at:datetime?` makes `published_at` a **nullable** datetime.
+:::
+
+When prompted, select the `blogging` feature package.
+
+This creates:
+- Post model with associations
+- Policy class with basic permissions
+- Controllers for CRUD operations
+- Database migration
+
+The generated post model includes:
+```ruby
+class Blogging::Post < Blogging::ResourceRecord
+  belongs_to :user
+  validates :title, presence: true
+  validates :content, presence: true
+end
+```
+
+Remember to apply the new migrations:
+```bash
+rails db:migrate
+```
+
+## Creating the Dashboard Portal
+
+Let's add a portal to manage our blog:
+
+```bash
+rails generate pu:pkg:portal dashboard
+```
+
+When prompted, select `user` for authentication.
+
+This creates a new portal package under `packages/dashboard_portal/` with:
+- Portal-specific controllers
+- Resource presentation layer
+- Dashboard views
+- Authenticated routes
+
+## Configure Routes
+
+Let's configure our application routes to properly handle authentication and dashboard access:
+
+::: code-group
+```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 ++]
+
+# Redirect to wherever login redirects to after account verification.
+verify_account_redirect { login_redirect }
+```
+
+```ruby [config/routes.rb]
+Rails.application.routes.draw do
+  # Other routes...
+
+  # Defines the root path route ("/")
+  # root "posts#index" # [!code --]
+  root to: redirect("/dashboard") # [!code ++]
+end
+```
+:::
+
+These changes ensure that:
+- Users are directed to the dashboard after signing up
+- Users are directed to the dashboard after logging in
+- Users are directed to the dashboard after logging out
+- The root URL (`/`) redirects to the dashboard
+- Account verification follows the same flow as login
+
+## Connecting Posts to Dashboard
+
+We can now connect our blog posts to the dashboard:
+
+```bash
+rails generate pu:res:conn
+```
+
+Select:
+1. Source feature: `blogging`
+2. Resources: `Blogging::Post`
+3. Portal: `dashboard_portal`
+
+This configures the routing and controllers to display posts in the dashboard.
+
+![Plutonium Posts Dashboard](/tutorial/plutonium-posts-dashboard.png)
+
+## Adding Comments
+
+Let's add commenting functionality:
+
+```bash
+rails generate pu:res:scaffold comment blogging/post:belongs_to \
+  user:belongs_to body:text
+
+rails db:migrate
+
+rails generate pu:res:conn
+```
+
+::: tip
+Note the use of the namespaced model in the association `blogging/post`.
+
+Plutonium has inbuilt support for handling namespaces, generating:
+```ruby
+# model
+belongs_to :post, class_name: "Blogging::Post"
+
+# migration
+t.belongs_to :post, null: false, foreign_key: {:to_table=>:blogging_posts}
+```
+:::
+
+This creates:
+- Comment model with associations
+- Policy controlling access
+- CRUD interface in dashboard
+- Proper routing configuration
+
+## Customizing the Interface
+
+### Post Table Customization
+
+We can customize how posts appear in the table view:
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+def permitted_attributes_for_index
+  [:user, :title, :published_at, :created_at]
+end
+```
+
+![Plutonium Posts Dashboard (Customized)](/tutorial/plutonium-posts-dashboard-customized.png)
+
+### Post Detail View
+
+Customize the post detail layout using display grids:
+
+```ruby
+# packages/blogging/app/definitions/blogging/post_definition.rb
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  display :user, class: "col-span-full"
+  display :title, class: "col-span-full"
+  display :content, class: "col-span-full"
+  display :published_at, class: "col-span-full"
+end
+```
+
+![Plutonium Posts Detail (Customized)](/tutorial/plutonium-posts-detail-customized.png)
+
+## Adding Publishing Functionality
+
+Let's add the ability to publish posts:
+
+::: code-group
+
+```ruby [post_definition.rb]
+# packages/blogging/app/definitions/blogging/post_definition.rb
+action :publish,
+       interaction: Blogging::Posts::Publish,
+       collection_record_action: false # do not show this on the table
+```
+
+```ruby [publish.rb]
+# packages/blogging/app/interactions/blogging/posts/publish.rb
+module Blogging
+  module Posts
+    class Publish < ResourceInteraction
+      presents label: "Publish Post", icon: Phlex::TablerIcons::Send
+      attribute :resource
+
+      def execute
+        if resource.update(published_at: Time.current)
+          succeed(resource)
+            .with_message("Post was successfully published")
+        else
+          failed(resource.errors)
+        end
+      end
+    end
+  end
+end
+```
+
+```ruby [post_policy.rb]
+# packages/blogging/app/policies/blogging/post_policy.rb
+
+def publish? # [!code ++]
+  !record.published_at # [!code ++]
+end # [!code ++]
+
+
+def permitted_attributes_for_create
+  [:user, :title, :content, :published_at] # [!code --]
+  [:user, :title, :content] # [!code ++]
+end
+```
+
+:::
+
+![Plutonium Publish Post](/tutorial/plutonium-publish-post.png)
+
+## Adding Comments Panel
+
+Enable viewing comments on posts:
+
+::: code-group
+
+```ruby [post.rb]
+# packages/blogging/app/models/blogging/post.rb
+has_many :comments
+```
+
+```ruby [post_policy.rb]
+# packages/blogging/app/policies/blogging/post_policy.rb
+def permitted_associations
+  %i[comments]
+end
+```
+
+:::
+
+![Plutonium Comments Panel](/tutorial/plutonium-association-panel.png)
+
+## Scoping Resources
+
+Ensure users only see their own content:
+
+```ruby
+# packages/dashboard_portal/lib/engine.rb
+module DashboardPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      scope_to_entity User, strategy: :current_user
+    end
+  end
+end
+```
+
+## Adding Nested Comments
+
+Enable adding comments directly from the post form:
+
+::: code-group
+
+```ruby [post_definition.rb]
+# packages/blogging/app/definitions/blogging/post_definition.rb
+nested_input :comments,
+  using: Blogging::CommentDefinition,
+  fields: %i[user body]
+```
+
+```ruby [post.rb]
+# packages/blogging/app/models/blogging/post.rb
+has_many :comments
+accepts_nested_attributes_for :comments # [!code ++]
+```
+
+```ruby [post_policy.rb]
+# packages/blogging/app/policies/blogging/post_policy.rb
+def permitted_attributes_for_create
+  [:user, :title, :content] # [!code --]
+  [:user, :title, :content, :comments] # [!code ++]
+end
+```
+
+:::
+
+![Plutonium Nested Comments](/tutorial/plutonium-nested-form.png)
+
+## Running the Application
+
+1. Start the Development server:
+```bash
+bin/dev
+```
+
+2. Visit `http://localhost:3000`
+
+3. Create a user account and start managing your blog!
+
+## What's Next?
+
+Some ideas for extending the application:
+- Add categories/tags for posts
+- Implement comment moderation
+- Add rich text editing for post content
+- Create a public-facing blog view
+- Add image attachments for posts
+- Implement social sharing
+
+## Conclusion
+
+In this tutorial, we've built a full-featured blog application with:
+- User authentication
+- Post management
+- Commenting system
+- Publishing workflow
+- Proper authorization
+- User-scoped content
+
+Plutonium helped us quickly scaffold and connect the pieces while maintaining clean separation of concerns through its package system.

data/docs/index.md

@@ -17,27 +17,31 @@ hero:
       link: /guide/what-is-plutonium
 
 features:
-  - title: Pro-Grade CRUD UI
-    details: Stunning, modern interface with rich field types to build powerful admin panels in minutes
+  # Core Value Proposition - Start with the main benefit
+  - title: Rich Resource Management
+    details: Beautiful, modern interfaces with production-ready components for rapid development
 
-  - title: Intelligent Fields
-    details: Zero-config field detection that matches your Rails models out of the box
+  # 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: Seamless Authentication
-    details: Use your existing auth or our Rodauth integration - get setup in seconds
+  - title: Advanced Authorization
+    details: Comprehensive access control built on Action Policy's proven authorization framework
 
-  - title: Enterprise Authorization
-    details: Industrial-strength access control powered by Action Policy's proven framework
+  - title: Seamless Authentication
+    details: Integrate your existing auth or use our Rodauth integration - ready in seconds
 
-  - title: Built-in Multitenancy
-    details: Row-level multitenancy that just works - perfect for SaaS and enterprise apps
+  # 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 with zero extra configuration
+    details: Complex resource relationships made simple through intelligent relationship mapping
 
-  - title: Custom Actions
-    details: Extend your admin panel with incredibly simple custom actions and workflows
+  # Extensibility Features - How it grows with your needs
+  - title: Extensible Workflows
+    details: Add custom actions and business workflows with a simple, declarative API
 
-  - title: Complete Builder Control
-    details: Total flexibility to customize every aspect of your admin UI with elegant builder APIs
+  - title: Flexible UI Customization
+    details: Customize any aspect of your interfaces with elegant builder APIs
 ---

data/lib/generators/pu/core/assets/templates/tailwind.config.js

@@ -1,12 +1,22 @@
 const { execSync } = require('child_process');
 const plutoniumGemPath = execSync("bundle show plutonium").toString().trim();
 const plutoniumTailwindConfig = require(`${plutoniumGemPath}/tailwind.options.js`)
+const tailwindPlugin = require('tailwindcss/plugin')
 
 module.exports = {
   darkMode: plutoniumTailwindConfig.darkMode,
   plugins: [
     // add plugins here
-  ].concat(plutoniumTailwindConfig.plugins.map((plugin) => require(plugin))),
+  ].concat(plutoniumTailwindConfig.plugins.map(function (plugin) {
+    switch (typeof plugin) {
+      case "function":
+        return tailwindPlugin(plugin)
+      case "string":
+        return require(plugin)
+      default:
+        throw Error(`unsupported plugin: ${plugin}: ${(typeof plugin)}`)
+    }
+  })),
   theme: plutoniumTailwindConfig.theme,
   content: [
     `${__dirname}/app/**/*.rb`,

data/lib/generators/pu/extra/colorized_logger/colorized_logger_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../../lib/plutonium_generators"
+
+module Pu
+  module Extra
+    class ColorizedLoggerGenerator < Rails::Generators::Base
+      include PlutoniumGenerators::Generator
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Set up a colorized logger"
+
+      def start
+        copy_file "config/initializers/colorized_logger.rb"
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+    end
+  end
+end

data/lib/generators/pu/extra/colorized_logger/templates/config/initializers/colorized_logger.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+return unless Rails.env.development?
+
+# Taken from https://gist.github.com/kyrylo/3d90f7a656d1a0accf244b8f1d25999b?permalink_comment_id=5264120#gistcomment-5264120
+
+module ColorizedLogger
+  %i[debug info warn error fatal unknown].each do |level|
+    color = case level
+    when :debug then "\e[0;36m"  # Cyan text
+    when :info then "\e[0;32m"  # Green text
+    when :warn then "\e[1;33m"  # Yellow text
+    when :error, :fatal then "\e[1;31m"  # Red text
+    else "\e[0m"  # Terminal default
+    end
+
+    define_method(level) do |progname = nil, &block|
+      super(color + (progname || (block && block.call)).to_s + "\e[0m")
+    end
+  end
+end
+Rails.logger.extend(ColorizedLogger)

data/lib/generators/pu/gem/standard/standard_generator.rb

@@ -10,7 +10,7 @@ module Pu
       desc "Set up standardrb"
 
       def start
-        bundle "standardrb"
+        bundle "standard", version: ">= 1.35.1"
       rescue => e
         exception "#{self.class} failed:", e
       end

data/lib/plutonium/core/controllers/authorizable.rb

@@ -26,7 +26,7 @@ module Plutonium
         end
 
         def entity_scope_for_authorize
-          scoped_to_entity? ? current_scoped_entity : nil
+          current_scoped_entity if scoped_to_entity?
         end
 
         def verify_authorized

data/lib/plutonium/resource/controller.rb

@@ -34,7 +34,7 @@ module Plutonium
         # Gets the resource class for the controller
         # @return [ActiveRecord::Base] The resource class
         def resource_class
-          return @resource_class if @resource_class.present?
+          return @resource_class if @resource_class
 
           name.to_s.gsub(/^#{current_package}::/, "").gsub(/Controller$/, "").classify.constantize
         rescue NameError
@@ -52,7 +52,7 @@ module Plutonium
       # Returns the resource record based on path parameters
       # @return [ActiveRecord::Base, nil] The resource record
       def resource_record
-        @resource_record ||= current_authorized_scope.from_path_param(params[:id]).first! if params[:id].present?
+        @resource_record ||= current_authorized_scope.from_path_param(params[:id]).first! if params[:id]
         @resource_record
       end
 
@@ -125,19 +125,23 @@ module Plutonium
       # Applies submitted resource params if they have been passed
       def maybe_apply_submitted_resource_params!
         ensure_get_request
-        resource_record.attributes = submitted_resource_params if params[resource_param_key].present?
+        resource_record.attributes = submitted_resource_params if params[resource_param_key]
       end
 
       # Returns the current parent based on path parameters
       # @return [ActiveRecord::Base, nil] The current parent
       def current_parent
-        return unless parent_route_param.present?
+        return unless parent_route_param
 
         @current_parent ||= begin
           parent_route_key = parent_route_param.to_s.gsub(/_id$/, "").to_sym
           parent_class = current_engine.resource_register.route_key_lookup[parent_route_key]
-          parent_scope = parent_class.from_path_param(params[parent_route_param])
-          parent_scope = parent_scope.associated_with(current_scoped_entity) if scoped_to_entity?
+          parent_scope = if scoped_to_entity?
+            parent_class.associated_with(current_scoped_entity)
+          else
+            parent_class.all
+          end
+          parent_scope = parent_scope.from_path_param(params[parent_route_param])
           current_parent = parent_scope.first!
           authorize! current_parent, to: :read?
           current_parent
@@ -153,7 +157,7 @@ module Plutonium
       # Returns the parent input parameter
       # @return [Symbol, nil] The parent input parameter
       def parent_input_param
-        return unless current_parent.present?
+        return unless current_parent
 
         resource_class.reflect_on_all_associations(:belongs_to).find { |assoc| assoc.klass.name == current_parent.class.name }&.name&.to_sym
       end
@@ -182,7 +186,7 @@ module Plutonium
       # Overrides parent parameters
       # @param [Hash] input_params The input parameters
       def override_parent_params(input_params)
-        if current_parent.present?
+        if current_parent
           if input_params.key?(parent_input_param) || resource_class.method_defined?(:"#{parent_input_param}=")
             input_params[parent_input_param] = current_parent
           end

data/lib/plutonium/resource/controllers/authorizable.rb

@@ -112,7 +112,7 @@ module Plutonium
         #
         # @return [Hash] default context for the current resource's policy
         def current_policy_context
-          {scope: current_parent || entity_scope_for_authorize}
+          {entity_scope: current_parent || entity_scope_for_authorize}
         end
 
         # Authorizes the current action for the given record of the current resource
@@ -130,7 +130,7 @@ module Plutonium
         #
         # @return [Array<Symbol>] the list of permitted attributes for the current action
         def permitted_attributes
-          @permitted_attributes ||= current_policy.send_with_report(:"permitted_attributes_for_#{action_name}")
+          @permitted_attributes ||= current_policy.send_with_report(:"permitted_attributes_for_#{action_name}").freeze
         end
 
         # Returns the list of permitted associations for the current resource