plutonium 0.24.1 → 0.24.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb793ad2d24a4aef3c7a5c46146260b019e6ab1af1e82a23c110379f96b51df6
-  data.tar.gz: 3926d88a01fa0a9ec45b2c072b0c8112e058082520fb4d2019f765a8cf2a97a3
+  metadata.gz: 26384f4aed52055be1bcc886fcb5df8c98d84297254ab95c8a5de40c6263f492
+  data.tar.gz: 870630d6315cc1e2964a6fea922e276f52957fcf7a0a6d381dc52d6e84a96c1e
 SHA512:
-  metadata.gz: 4bf56145b9fc26fe50d167bfdffd347488c4be2d7a32c985d698ca4c24e40fc98cfc26e3a3c5cf88fca7dbf8de934f4c4974e8d394b347918c1f1d962484ace6
-  data.tar.gz: dacc135a569a2c5ec92134e7cf2670948680622c529514e2ddb996318e4e120330081ea8fd122b6c4dd9e29e3e6c838dcb037ca0939f65e16a43c73f2f50851e
+  metadata.gz: 649df44bd7ad78590c769afffacbbd604919c246f3e1db98eb0397509d7111b24bc9eec2a13bd311c59ac2d1a42d1b9cef06ce7a8e15a6ae69012066ce645a67
+  data.tar.gz: 1ac6bc80a0788d79c6d99211134a45afce8ed54d6dfff156766c44587314951a561733de01c7c3a8e6abc41d06c0235542a7f4085ca4041fb599459497f18e0b

data/app/views/plutonium/_resource_header.html.erb

@@ -1,6 +1,6 @@
 <%= render Plutonium::UI::Layout::Header.new do |header| %>
   <% header.with_brand_logo do %>
-    <%= resource_logo_tag(classname: "h-10") %>
+    <%= resource_logo_tag(classname: "h-10 rounded-md") %>
   <% end %>
 
   <% header.with_action do %>

data/docs/.vitepress/config.ts

@@ -56,6 +56,7 @@ export default defineConfig(withMermaid({
           items: [
             { text: "Resources", link: "/guide/deep-dive/resources" },
             { text: "Authorization", link: "/guide/deep-dive/authorization" },
+            { text: "Multitenancy", link: "/guide/deep-dive/multitenancy" },
             { text: "Modules", link: "/modules/" },
           ]
         },

data/docs/guide/deep-dive/multitenancy.md

@@ -0,0 +1,256 @@
+# Deep Dive: Multitenancy
+
+Plutonium is designed to make building sophisticated, multi-tenant applications straightforward. Multitenancy allows you to serve distinct groups of users (like different companies or teams) from a single application instance, ensuring each group's data is kept private and isolated.
+
+This is achieved through a powerful feature called **Entity Scoping**, which automates data isolation, URL generation, and authorization with minimal setup.
+
+::: tip What You'll Learn
+- The core concept of Entity Scoping
+- A step-by-step guide to configuring multitenancy
+- The practical benefits of automatic data isolation and routing
+- Advanced patterns for complex multi-tenant scenarios
+- Best practices for security, testing, and performance
+:::
+
+## How Entity Scoping Works
+
+Entity Scoping is the heart of Plutonium's multitenancy. Instead of manually filtering data in every controller and model, you declare a **Scoping Entity** for a user-facing **Portal**. This entity is typically a model like `Organization`, `Account`, or `Workspace`.
+
+Once configured, Plutonium handles the rest automatically.
+
+::: code-group
+```ruby [Without Plutonium Scoping]
+# Manual filtering is required everywhere
+class PostsController < ApplicationController
+  def index
+    # Manually find the organization and scope posts
+    @organization = Organization.find(params[:organization_id])
+    @posts = @organization.posts
+  end
+
+  def create
+    # Manually associate new records with the organization
+    @organization = Organization.find(params[:organization_id])
+    @post = @organization.posts.build(post_params)
+    # ...
+  end
+end
+```
+
+```ruby [With Plutonium Scoping]
+# Scoping is automatic and declarative
+class PostsController < ResourceController
+  def index
+    # current_authorized_scope automatically returns posts scoped to the current organization
+    # When using path strategy: URL -> /organizations/123/posts
+    # When using subdomain strategy: URL -> /posts (on acme.yourapp.com)
+  end
+
+  def create
+    # resource_params automatically includes the current organization association
+    # Scoping works regardless of the strategy used
+  end
+end
+```
+:::
+
+## Setting Up Your Multi-Tenant Portal
+
+Configuring multitenancy involves three main steps: defining your strategy, implementing it, and ensuring your models are correctly associated.
+
+### 1. Configure Your Portal Engine
+
+First, you tell your portal which entity to scope to and which strategy to use. This is done in the portal's `engine.rb` file using `scope_to_entity`.
+
+A **Scoping Strategy** tells Plutonium how to identify the current tenant for each request.
+
+::: code-group
+```ruby [Path Strategy (Most Common)]
+# packages/admin_portal/lib/engine.rb
+# Tenant is identified by a URL parameter, e.g., /organizations/:organization_id
+scope_to_entity Organization, strategy: :path
+```
+
+```ruby [Custom Strategy (Subdomain)]
+# packages/customer_portal/lib/engine.rb
+# Tenant is identified by the a custom strategy that checks the subdomain, e.g., acme.yourapp.com
+scope_to_entity Organization, strategy: :current_organization
+```
+
+```ruby [Custom Parameter Key]
+# packages/client_portal/lib/engine.rb
+# Same as :path, but with a custom parameter name.
+scope_to_entity Client,
+  strategy: :path,
+  param_key: :client_slug # URL -> /clients/:client_slug
+```
+:::
+
+You can also use any custom name for your strategy method (the method name becomes the strategy).
+
+### 2. Implement the Strategy Method
+
+If you use any strategy other than `:path`, you must implement a controller method that returns the current tenant object. The method name must exactly match the strategy name.
+
+This logic typically lives in your portal's base controller concern.
+
+::: code-group
+```ruby [Subdomain Strategy]
+# packages/customer_portal/app/controllers/customer_portal/concerns/controller.rb
+private
+
+# Method name :current_organization matches the strategy
+def current_organization
+  @current_organization ||= Organization.find_by!(subdomain: request.subdomain)
+rescue ActiveRecord::RecordNotFound
+  redirect_to root_path, error: "Invalid organization subdomain"
+end
+```
+
+```ruby [Session-Based Strategy]
+# packages/internal_portal/app/controllers/internal_portal/concerns/controller.rb
+# In engine.rb: scope_to_entity Workspace, strategy: :current_workspace
+private
+
+def current_workspace
+  return @current_workspace if defined?(@current_workspace)
+
+  workspace_id = session[:workspace_id] || params[:workspace_id]
+  @current_workspace = current_user.workspaces.find(workspace_id)
+
+  session[:workspace_id] = @current_workspace.id # Remember for next request
+  @current_workspace
+rescue ActiveRecord::RecordNotFound
+  redirect_to workspace_selection_path, error: "Please select a workspace"
+end
+```
+:::
+
+### 3. Connect Your Models
+
+Plutonium needs to understand how your resources relate to the scoping entity. It automatically discovers these relationships in three ways:
+
+::: code-group
+```ruby [1. Direct Association (Preferred)]
+# The model belongs directly to the scoping entity.
+class Post < ApplicationRecord
+  belongs_to :organization # Direct link
+end
+```
+
+```ruby [2. Indirect Association]
+# The model belongs to another model that has the direct link.
+# Plutonium automatically follows the chain: Comment -> Post -> Organization
+class Comment < ApplicationRecord
+  belongs_to :post
+  has_one :organization, through: :post # Indirect link
+end
+```
+
+```ruby [3. Custom Scope (For Complex Cases)]
+# For complex relationships, you can define an explicit scope.
+# The scope name must be `associated_with_#{scoping_entity_name}`.
+class Invoice < ApplicationRecord
+  belongs_to :customer
+
+  scope :associated_with_organization, ->(organization) do
+    joins(customer: :organization_memberships)
+      .where(organization_memberships: { organization_id: organization.id })
+  end
+end
+```
+:::
+
+## The Benefits in Practice
+
+With this setup complete, you gain several powerful features across your portal.
+
+### Tenant-Aware Routing
+
+Your application's URLs are automatically transformed to include the tenant context, and Plutonium's URL helpers adapt accordingly.
+
+- **URL Transformation:** Routes like `/posts` and `/posts/123` become `/:organization_id/posts` and `/:organization_id/posts/123`.
+- **Automatic URL Generation:** The `resource_url_for` helper automatically includes the current tenant in all generated URLs, so links and forms work without any changes.
+
+```ruby
+# Both of these helpers are automatically aware of the current tenant.
+resource_url_for(Post) # => "/organizations/456/posts"
+form_with model: @post # action -> "/organizations/456/posts/123"
+```
+
+### Secure Data Scoping
+
+All data access is automatically and securely filtered to the current tenant.
+
+- **Query Scoping:** A query like `Post.all` is automatically converted to `current_scoped_entity.posts`. This prevents accidental data leaks.
+- **Record Scoping:** When fetching a single record (e.g., for `show` or `edit`), Plutonium ensures it belongs to the current tenant. If not, it raises an `ActiveRecord::RecordNotFound` error, just as if the record didn't exist.
+
+### Integrated Authorization
+
+The current `entity_scope` is seamlessly passed to your authorization policies, allowing for fine-grained, tenant-aware rules.
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  # `entity_scope` is automatically available in all policy methods.
+  authorize :entity_scope, allow_nil: true
+
+  def update?
+    # A user can only update a post if it belongs to their current tenant
+    # AND they are the author of the post.
+    record.organization == entity_scope && record.author == user
+  end
+
+  relation_scope do |relation|
+    # `super` automatically applies the base entity scoping.
+    relation = super(relation)
+
+    # Add more logic: Admins can see all posts within their organization,
+    # but others can only see published posts.
+    user.admin? ? relation : relation.where(published: true)
+  end
+end
+```
+
+## Security Best Practices
+
+Securing a multi-tenant application is critical. While Plutonium provides strong defaults, you must ensure your implementation is secure.
+
+::: warning Always Validate Tenant Access
+A user might belong to multiple tenants. It's crucial to verify that the logged-in user has permission to access the tenant specified in the URL. Failure to do so could allow a user to see data from another organization they don't belong to.
+:::
+
+```ruby
+# ✅ Good: Proper tenant validation
+# In your custom strategy method or a before_action:
+private
+
+def current_organization
+  @current_organization ||= begin
+    # Find the organization from the URL
+    organization = Organization.find(params[:organization_id])
+
+    # CRITICAL: Verify the current user is a member of that organization
+    unless current_user.organizations.include?(organization)
+      raise ActionPolicy::Unauthorized, "Access denied to organization"
+    end
+
+    organization
+  end
+end
+
+# ❌ Dangerous: No access validation
+def current_organization
+  # This allows ANY authenticated user to access ANY organization's data
+  # simply by changing the ID in the URL.
+  Organization.find(params[:organization_id])
+end
+```
+
+## Advanced Patterns
+
+Plutonium's scoping is flexible enough to handle more complex scenarios.
+
+- **Multi-Level Tenancy:** For hierarchical tenancy (e.g., Company -> Department), you can apply the primary scope at the engine level and add secondary scoping logic inside your policies' `relation_scope`.
+- **Cross-Tenant Data Access:** For resources that can be shared, define a custom `associated_with_...` scope that includes both shared records and records belonging to the current tenant.
+- **Tenant Switching:** Build a controller that allows users to change their active tenant by updating a `session` key, then use a session-based scoping strategy to read it.
+- **API Multitenancy:** Create a custom scoping strategy (e.g., `:api_tenant`) that authenticates and identifies the tenant based on an API key or JWT from the request headers.

data/docs/modules/controller.md

@@ -188,7 +188,7 @@ Portal Controllers provide specialized functionality for multi-tenant applicatio
 
 ```ruby
 module AdminPortal
-  class PostsController < PlutoniumController
+  class PostsController < ResourceController
     include AdminPortal::Concerns::Controller
 
     # Automatically inherits from ::PostsController

data/docs/modules/core.md

@@ -76,7 +76,7 @@ The Bootable concern automatically detects which package and engine a controller
 
 ```ruby
 # In packages/admin_portal/app/controllers/users_controller.rb
-class UsersController < PlutoniumController
+class UsersController < ResourceController
   # Automatically detects:
   # current_package => AdminPortal
   # current_engine  => AdminPortal::Engine
@@ -221,13 +221,13 @@ The Core module is typically used through other Plutonium modules:
 
 ```ruby
 # For resource controllers
-class UsersController < PlutoniumController
+class UsersController < ResourceController
   include Plutonium::Resource::Controller
   # Core module included automatically
 end
 
 # For portal controllers
-class DashboardController < PlutoniumController
+class DashboardController < ResourceController
   include Plutonium::Portal::Controller
   # Core module included automatically
 end
@@ -294,12 +294,12 @@ Let the Bootable concern handle package detection automatically:
 
 ```ruby
 # ✅ Good - automatic detection
-class AdminPortal::UsersController < PlutoniumController
+class AdminPortal::UsersController < ResourceController
   # Package and engine automatically detected
 end
 
 # ❌ Avoid - manual configuration
-class UsersController < PlutoniumController
+class UsersController < ResourceController
   def current_package
     AdminPortal # Don't override unless necessary
   end

data/lib/plutonium/ui/display/resource.rb

@@ -61,7 +61,7 @@ module Plutonium
               identifier: title.parameterize,
               title: -> { h5(class: "text-2xl font-bold tracking-tight text-gray-900 dark:text-white") { title } }
             ) do
-              FrameNavigatorPanel(title: "", src:)
+              FrameNavigatorPanel(title: "", src:, panel_id: "association-panel-#{title.parameterize}")
             end
           end
 

data/lib/plutonium/ui/form/interaction.rb

@@ -15,8 +15,34 @@ module Plutonium
         private
 
         def form_action
-          # interactive action forms post to the same page
-          nil
+          # Build the correct commit URL for the interactive action
+          action = helpers.current_interactive_action
+          return nil unless action
+
+          # Create route options for the commit action (convert GET to POST action)
+          commit_route_options = action.route_options.merge(
+            Plutonium::Action::RouteOptions.new(
+              method: :post,
+              action: commit_action_name(action.route_options.url_options[:action])
+            )
+          )
+
+          # Use existing infrastructure to build the URL
+          subject = action.record_action? ? helpers.resource_record! : helpers.resource_class
+          helpers.route_options_to_url(commit_route_options, subject)
+        end
+
+        def commit_action_name(action_name)
+          case action_name
+          when :interactive_record_action
+            :commit_interactive_record_action
+          when :interactive_resource_action
+            :commit_interactive_resource_action
+          when :interactive_collection_action
+            :commit_interactive_bulk_action
+          else
+            action_name
+          end
         end
 
         def initialize_attributes

data/lib/plutonium/ui/frame_navigator_panel.rb

@@ -41,20 +41,22 @@ module Plutonium
       end
 
       class PanelContent < Plutonium::UI::Component::Base
-        def initialize(src:)
+        def initialize(id:, src:)
+          @id = id
           @src = src
         end
 
         def view_template
-          DynaFrameHost src: @src, loading: :lazy, data: {"frame-navigator-target": "frame"} do
+          DynaFrameHost id: @id, src: @src, loading: :lazy, data: {"frame-navigator-target": "frame"} do
             SkeletonTable()
           end
         end
       end
 
-      def initialize(title:, src:)
+      def initialize(title:, src:, panel_id: nil)
         @title = title
         @src = src
+        @panel_id = panel_id
       end
 
       def view_template
@@ -65,7 +67,7 @@ module Plutonium
             panel.with_item PanelItem.new(label: "Back", icon: Phlex::TablerIcons::ChevronLeft, data_frame_navigator_target: "backButton")
             panel.with_item PanelItem.new(label: "Refresh", icon: Phlex::TablerIcons::RefreshDot, data_frame_navigator_target: "refreshButton")
             panel.with_item PanelLink.new(label: "Maximize", icon: Phlex::TablerIcons::WindowMaximize, href: @src, data_frame_navigator_target: "maximizeLink")
-            panel.with_content PanelContent.new(src: @src)
+            panel.with_content PanelContent.new(id: @panel_id, src: @src)
           end
         end
       end

data/lib/plutonium/ui/layout/rodauth_layout.rb

@@ -11,7 +11,7 @@ module Plutonium
         end
 
         def main_attributes = mix(super, {
-          class: "flex flex-col items-center justify-center px-6 py-8 mx-auto lg:py-0"
+          class: "flex flex-col items-center justify-center gap-2 px-6 py-8 mx-auto lg:py-0"
         })
 
         def render_content(&)
@@ -25,8 +25,8 @@ module Plutonium
         end
 
         def render_logo
-          link_to root_path, class: "flex items-center text-2xl font-semibold text-gray-900 dark:text-white" do
-            helpers.resource_logo_tag classname: "w-24 h-24 mr-2"
+          link_to root_path, class: "flex items-center text-2xl font-semibold text-gray-900 dark:text-white mb-2" do
+            helpers.resource_logo_tag classname: "w-24 h-24 mr-2 rounded-md"
           end
         end
 

data/lib/plutonium/version.rb

@@ -1,5 +1,5 @@
 module Plutonium
-  VERSION = "0.24.1"
+  VERSION = "0.24.3"
   NEXT_MAJOR_VERSION = VERSION.split(".").tap { |v|
     v[1] = v[1].to_i + 1
     v[2] = 0

data/plutonium-blog-post.md

@@ -0,0 +1,45 @@
+# So, You've Decided to Build Another SaaS...
+
+Let me guess. You have a brilliant idea for a new web application. It's going to be the next big thing. You're fired up, ready to code. You spin up a new Rails app, and then it hits you. The boilerplate. User authentication, admin panels, data tables, filters, authorization policies... Suddenly your brilliant idea is buried under a mountain of tedious, repetitive work.
+
+We've all been there. Rails is great, but for complex applications, the initial setup can be a drag. You end up writing the same code over and over again, just to get to the starting line.
+
+What if you could skip all that? What if you could get straight to building the features that make your app unique?
+
+Enter Plutonium.
+
+## What's This Plutonium Thing, Anyway?
+
+Plutonium is a Rapid Application Development (RAD) toolkit for Rails. That's a fancy way of saying it helps you build feature-rich, enterprise-ready applications at a ridiculous speed. It's not a replacement for Rails; it's a high-level abstraction built on top of it. You still get all the Rails goodness you know and love, but with a whole lot of awesome packed on top.
+
+The core idea behind Plutonium is its **Resource-Oriented Architecture**. In a Plutonium app, everything is a "Resource". A user is a Resource, a product is a Resource, a blog post is a Resource. You get the idea.
+
+But these aren't just your plain old `ActiveRecord` models. A Plutonium Resource is a supercharged, self-contained unit that knows how to do a bunch of things on its own. Each Resource is made up of four parts:
+
+*   **The Model:** This is your good old `ActiveRecord` model. Nothing new here. It still handles your database interactions, validations, and associations.
+*   **The Definition:** This is where things get interesting. The Definition tells Plutonium how the Resource should look and behave in the UI. You define fields, search functionality, filters, and custom actions, all in a clean, declarative way.
+*   **The Policy:** This is for authorization. It controls who can do what with a Resource. It's like having a bouncer for every piece of data in your app.
+*   **The Actions:** These are for custom operations. Think of anything that's not a simple create, read, update, or delete. For example, an action to "publish" a blog post or "deactivate" a user.
+
+This structure keeps your code incredibly organized and easy to reason about.
+
+## Stop Organizing, Start Building
+
+One of the biggest headaches in a large Rails app is keeping the code organized. As the app grows, `app/models`, `app/controllers`, and `app/views` can become a real mess. Plutonium solves this with a modular packaging system.
+
+There are two types of packages:
+
+*   **Feature Packages:** These are where your core business logic lives. They're self-contained modules focused on a specific domain, like "invoicing" or "user management". They don't have any web-facing parts, just the raw logic.
+*   **Portal Packages:** These are the user interfaces. A portal takes one or more feature packages and presents them to a specific type of user, like an "admin portal" or a "customer portal".
+
+This separation is a game-changer. It forces you to think about your application in a more structured way, which pays off big time in the long run.
+
+And if you're building a multi-tenant SaaS app, you'll love this: Plutonium has built-in support for multi-tenancy. You can scope all your data to an entity like an `Organization` or `Account` with a single line of code in your portal configuration. Plutonium handles the rest, automatically ensuring that users only see the data that belongs to them.
+
+To top it all off, Plutonium comes with a bunch of generators that create all the boilerplate for you. Need a new feature package? `rails generate pu:pkg:package my_feature`. Need a new resource with a model, definition, policy, and all the fixings? `rails generate pu:res:scaffold post title:string content:text`. It's like having a junior developer who does all the boring work for you.
+
+## Is Plutonium for You?
+
+Plutonium is not for every project. If you're building a simple blog or a marketing site, it's probably overkill. But if you're building a complex business application, a multi-tenant SaaS platform, an admin system, or a CMS, Plutonium can be a massive productivity boost.
+
+So, next time you have that brilliant idea for a new app, maybe give Plutonium a try. You might just find that you can get from idea to launch a whole lot faster.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plutonium
 version: !ruby/object:Gem::Version
-  version: 0.24.1
+  version: 0.24.3
 platform: ruby
 authors:
 - Stefan Froelich
@@ -495,6 +495,7 @@ files:
 - docs/api-examples.md
 - docs/guide/cursor-rules.md
 - docs/guide/deep-dive/authorization.md
+- docs/guide/deep-dive/multitenancy.md
 - docs/guide/deep-dive/resources.md
 - docs/guide/getting-started/01-installation.md
 - docs/guide/index.md
@@ -881,6 +882,7 @@ files:
 - lib/tasks/.keep
 - package-lock.json
 - package.json
+- plutonium-blog-post.md
 - postcss-gem-import.js
 - postcss.config.js
 - public/.keep