plutonium 0.37.0 → 0.38.0

data/docs/guides/index.md

@@ -27,6 +27,10 @@ These guides show you how to accomplish specific tasks, with complete examples.
 
 - [Theming](./theming) - Customize colors, styles, and branding
 
+### Help
+
+- [Troubleshooting](./troubleshooting) - Common issues and solutions
+
 ## Finding What You Need
 
 | I want to... | Guide |
@@ -39,6 +43,7 @@ These guides show you how to accomplish specific tasks, with complete examples.
 | Separate data by company | [Multi-tenancy](./multi-tenancy) |
 | Add search to a list | [Search and Filtering](./search-filtering) |
 | Change the color scheme | [Theming](./theming) |
+| Fix a confusing error | [Troubleshooting](./troubleshooting) |
 
 ## Looking for Reference Docs?
 

data/docs/guides/nested-resources.md

@@ -4,7 +4,7 @@ This guide covers setting up parent/child resource relationships.
 
 ## Overview
 
-Nested resources create URLs like `/posts/1/comments` where comments belong to a specific post. Plutonium automatically handles:
+Nested resources create URLs like `/posts/1/nested_comments` where comments belong to a specific post. Plutonium automatically handles:
 
 - Scoping queries to the parent
 - Assigning parent to new records
@@ -12,6 +12,8 @@ Nested resources create URLs like `/posts/1/comments` where comments belong to a
 - URL generation with parent context
 - Breadcrumb navigation
 
+Plutonium supports both `has_many` (plural routes) and `has_one` (singular routes) associations.
+
 ## Setting Up Nested Resources
 
 ### 1. Define the Association
@@ -20,12 +22,17 @@ Nested resources create URLs like `/posts/1/comments` where comments belong to a
 # Parent model
 class Post < ResourceRecord
   has_many :comments, dependent: :destroy
+  has_one :post_metadata, dependent: :destroy
 end
 
-# Child model
+# Child models
 class Comment < ResourceRecord
   belongs_to :post
 end
+
+class PostMetadata < ResourceRecord
+  belongs_to :post
+end
 ```
 
 ### 2. Register Both Resources
@@ -35,15 +42,25 @@ end
 AdminPortal::Engine.routes.draw do
   register_resource ::Post
   register_resource ::Comment
+  register_resource ::PostMetadata
 end
 ```
 
-Plutonium automatically creates nested routes based on the `belongs_to` association:
-- `GET /posts/:post_id/comments`
-- `GET /posts/:post_id/comments/new`
-- `GET /posts/:post_id/comments/:id`
+Plutonium automatically creates nested routes with a `nested_` prefix based on the `belongs_to` association:
+
+**has_many routes (plural):**
+- `GET /posts/:post_id/nested_comments`
+- `GET /posts/:post_id/nested_comments/new`
+- `GET /posts/:post_id/nested_comments/:id`
 - etc.
 
+**has_one routes (singular):**
+- `GET /posts/:post_id/nested_post_metadata`
+- `GET /posts/:post_id/nested_post_metadata/new`
+- `GET /posts/:post_id/nested_post_metadata/edit`
+
+The `nested_` prefix prevents route conflicts when the same resource is registered both as a top-level and nested resource.
+
 ### 3. Enable Association Panel
 
 Show comments on the post detail page:
@@ -112,30 +129,46 @@ parent_input_param  # => :post
 Use `resource_url_for` with the `parent:` option:
 
 ```ruby
-# Child collection
+# Child collection (has_many)
 resource_url_for(Comment, parent: @post)
-# => /posts/123/comments
+# => /posts/123/nested_comments
 
 # Child record
 resource_url_for(@comment, parent: @post)
-# => /posts/123/comments/456
+# => /posts/123/nested_comments/456
 
 # New child form
 resource_url_for(Comment, action: :new, parent: @post)
-# => /posts/123/comments/new
+# => /posts/123/nested_comments/new
 
 # Edit child
 resource_url_for(@comment, action: :edit, parent: @post)
-# => /posts/123/comments/456/edit
+# => /posts/123/nested_comments/456/edit
+
+# Singular resource (has_one)
+resource_url_for(@post_metadata, parent: @post)
+# => /posts/123/nested_post_metadata
+
+resource_url_for(PostMetadata, action: :new, parent: @post)
+# => /posts/123/nested_post_metadata/new
 ```
 
 Within a nested context, `parent:` defaults to `current_parent`:
 
 ```ruby
-# In CommentsController under /posts/:post_id/comments
+# In CommentsController under /posts/:post_id/nested_comments
 resource_url_for(@comment)  # parent: current_parent is automatic
 ```
 
+### Cross-Package URL Generation
+
+Generate URLs for resources in a different package:
+
+```ruby
+# From AdminPortal, generate URL to CustomerPortal resource
+resource_url_for(@comment, parent: @post, package: CustomerPortal)
+```
+
 ## Presentation Hooks
 
 Control whether the parent field appears:
@@ -167,23 +200,47 @@ The parent is authorized for `:read?` before being returned:
 authorize! parent, to: :read?
 ```
 
-### Entity Scope Context
+### Parent Scoping Context
 
-The parent is passed to child policies as `entity_scope`:
+For nested resources, policies receive `parent` and `parent_association` context. This is used for automatic query scoping:
 
 ```ruby
 class CommentPolicy < ResourcePolicy
-  def create?
-    # entity_scope is the parent post
-    entity_scope.present? && user.can_comment_on?(entity_scope)
-  end
+  # Available context:
+  # - parent: the parent record (e.g., Post instance)
+  # - parent_association: the association name (e.g., :comments)
+  # - entity_scope: the scoped entity (for multi-tenancy)
 
-  def update?
-    record.user_id == user.id
+  relation_scope do |relation|
+    relation = super(relation)  # Applies parent scoping automatically
+    relation
   end
+end
+```
 
-  def destroy?
-    record.user_id == user.id || entity_scope&.user_id == user.id
+**Parent scoping takes precedence over entity scoping** - when a parent is present, the policy scopes via the parent association rather than the entity scope. This prevents double-scoping since the parent was already authorized and entity-scoped.
+
+### has_many vs has_one Scoping
+
+For **has_many** associations, scoping uses the association directly:
+```ruby
+parent.send(parent_association)  # e.g., post.comments
+```
+
+For **has_one** associations, scoping uses a where clause:
+```ruby
+relation.where(foreign_key => parent.id)  # e.g., where(post_id: post.id)
+```
+
+### Entity Scope Fallback
+
+When no parent is present (top-level resource access), entity_scope is used:
+
+```ruby
+class CommentPolicy < ResourcePolicy
+  def create?
+    # entity_scope is available for multi-tenancy
+    entity_scope.present? && user.can_comment_on?(entity_scope)
   end
 end
 ```
@@ -195,7 +252,7 @@ Add role-based filtering on top of parent scoping:
 ```ruby
 class CommentPolicy < ResourcePolicy
   relation_scope do |relation|
-    relation = super(relation)  # Applies associated_with(entity_scope)
+    relation = super(relation)  # Applies parent scoping first
 
     if user.moderator?
       relation
@@ -206,6 +263,33 @@ class CommentPolicy < ResourcePolicy
 end
 ```
 
+### default_relation_scope is Required
+
+Plutonium verifies that `default_relation_scope` is called in every `relation_scope` to prevent multi-tenancy leaks:
+
+```ruby
+# ❌ This will raise an error
+relation_scope do |relation|
+  relation.where(approved: true)  # Missing default_relation_scope!
+end
+
+# ✅ Correct
+relation_scope do |relation|
+  default_relation_scope(relation).where(approved: true)
+end
+```
+
+When overriding an inherited scope but still wanting parent scoping:
+
+```ruby
+class AdminCommentPolicy < CommentPolicy
+  relation_scope do |relation|
+    # Replace inherited scope but keep parent scoping
+    default_relation_scope(relation)
+  end
+end
+```
+
 ## Association Panels
 
 Associations listed in `permitted_associations` appear on the parent's show page:
@@ -257,15 +341,34 @@ class PostPolicy < ResourcePolicy
 end
 ```
 
+## has_one Associations
+
+Plutonium supports `has_one` associations with singular routes:
+
+```ruby
+class Post < ResourceRecord
+  has_one :post_metadata, dependent: :destroy
+end
+```
+
+Routes generated:
+- `GET /posts/:post_id/nested_post_metadata` - Show metadata
+- `GET /posts/:post_id/nested_post_metadata/new` - New metadata form
+- `GET /posts/:post_id/nested_post_metadata/edit` - Edit metadata form
+- `PATCH /posts/:post_id/nested_post_metadata` - Update metadata
+- `DELETE /posts/:post_id/nested_post_metadata` - Delete metadata
+
+Note: No `:id` parameter in singular routes - only one record can exist per parent.
+
 ## Nesting Depth
 
 Plutonium supports **one level of nesting**:
 
-- `/posts/:post_id/comments` (parent → child)
-- `/comments/:comment_id/replies` (parent → child)
+- `/posts/:post_id/nested_comments` (parent → child)
+- `/comments/:comment_id/nested_replies` (parent → child)
 
 Not supported:
-- `/posts/:post_id/comments/:comment_id/replies` (grandparent → parent → child)
+- `/posts/:post_id/nested_comments/:comment_id/nested_replies` (grandparent → parent → child)
 
 ### Working with Deep Hierarchies
 
@@ -295,9 +398,9 @@ end
 ```
 
 Generates nested routes:
-- `POST /posts/:post_id/comments/:id/approve`
-- `POST /posts/:post_id/comments/:id/flag`
-- `GET /posts/:post_id/comments/pending`
+- `POST /posts/:post_id/nested_comments/:id/approve`
+- `POST /posts/:post_id/nested_comments/:id/flag`
+- `GET /posts/:post_id/nested_comments/pending`
 
 ## Breadcrumbs
 

data/docs/guides/troubleshooting.md

@@ -0,0 +1,82 @@
+# Troubleshooting
+
+Common issues and their solutions when working with Plutonium.
+
+## Resource Class Detection
+
+### "Failed to determine the resource class" Error
+
+**Error messages:**
+```
+NameError: Failed to determine the resource class for MyPortal::PostMetadataController.
+Rails singularized "PostMetadata" to "PostMetadatum", but "PostMetadata" exists.
+Add an inflection rule to config/initializers/inflections.rb.
+```
+
+or:
+
+```
+NameError: Failed to determine the resource class.
+Please call `controller_for(MyResource)` in MyPortal::MyResourceController.
+```
+
+**Cause:** Plutonium infers the resource class from the controller name by singularizing it. For resources with names that don't follow standard Rails pluralization (like `PostMetadata`), Rails may singularize incorrectly (`PostMetadata` → `PostMetadatum`). Plutonium detects this and provides a helpful error message.
+
+**Solution:** Add a custom inflection rule in `config/initializers/inflections.rb`:
+
+```ruby
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  # Preserve "Metadata" when singularizing (e.g., PostMetadata stays PostMetadata)
+  inflect.singular(/(M)etadata$/i, '\1etadata')
+end
+```
+
+This ensures Rails correctly handles the singularization throughout your application, including:
+- Controller to model resolution
+- Route generation
+- Association lookups
+
+**Alternative:** If you can't modify inflections, explicitly set the resource class in your controller:
+
+```ruby
+class MyPortal::PostMetadataController < MyPortal::ResourceController
+  controller_for Blogging::PostMetadata
+end
+```
+
+### Common Words Needing Inflection Rules
+
+| Word | Without Rule | With Rule | Inflection |
+|------|--------------|-----------|------------|
+| Metadata | `PostMetadatum` | `PostMetadata` | `inflect.singular(/(M)etadata$/i, '\1etadata')` |
+| Media | `PostMedium` | `PostMedia` | `inflect.singular(/(M)edia$/i, '\1edia')` |
+| Data | `PostDatum` | `PostData` | `inflect.singular(/(D)ata$/i, '\1ata')` |
+| Criteria | `SearchCriterium` | `SearchCriteria` | `inflect.singular(/(C)riteria$/i, '\1riteria')` |
+
+## URL Generation
+
+### Wrong URLs for Nested Resources
+
+**Symptom:** URLs for nested resources include unexpected IDs or route to the wrong path.
+
+**Cause:** Rails "param recall" fills in missing parameters from the current request when generating URLs. This can cause issues when both top-level and nested routes exist for the same resource.
+
+**Solution:** Plutonium handles this automatically by using named route helpers for nested resources. Ensure you're using `resource_url_for` instead of `url_for`:
+
+```ruby
+# Good - uses Plutonium's smart URL generation
+resource_url_for(@comment, parent: @post)
+
+# May have issues with param recall
+url_for(controller: 'comments', action: 'show', id: @comment.id)
+```
+
+## Need More Help?
+
+If you encounter an issue not covered here, please [open an issue](https://github.com/radioactive-labs/plutonium-core/issues) on GitHub.
+
+## Related
+
+- [Nested Resources Guide](./nested-resources)
+- [Adding Resources Guide](./adding-resources)
+- [Rails Inflections Documentation](https://api.rubyonrails.org/classes/ActiveSupport/Inflector/Inflections.html)

data/docs/reference/controller/index.md

@@ -258,7 +258,7 @@ end
 Parent records are automatically resolved:
 
 ```ruby
-# Route: /users/:user_id/posts/:id
+# Route: /users/:user_id/nested_posts/:id
 class PostsController < ::ResourceController
   # current_parent returns the User
   # resource_record! returns the Post scoped to that User

data/docs/reference/definition/fields.md

@@ -232,6 +232,39 @@ column :status, align: :center  # Center
 column :amount, align: :end     # Right
 ```
 
+## Value Formatting
+
+Use `formatter` for simple value transformations without a full block:
+
+```ruby
+# Truncate long text
+column :description, formatter: ->(value) { value&.truncate(30) }
+
+# Format numbers
+column :price, formatter: ->(value) { "$%.2f" % value if value }
+
+# Transform values
+column :status, formatter: ->(value) { value&.humanize&.upcase }
+```
+
+The `formatter` option:
+- Receives the field value as its argument
+- Returns the transformed value for display
+- Works with `column` and `display` declarations
+- Is simpler than block syntax when you only need to transform the value
+
+**formatter vs block:** Use `formatter` when you only need the value. Use a block when you need access to the full record:
+
+```ruby
+# formatter - receives just the value
+column :name, formatter: ->(value) { value&.titleize }
+
+# block - receives the full record
+column :full_name do |record|
+  "#{record.first_name} #{record.last_name}"
+end
+```
+
 ## Nested Inputs
 
 Render inline forms for associated records. Requires `accepts_nested_attributes_for` on the model.

data/docs/reference/model/index.md

@@ -67,7 +67,7 @@ class Comment < ResourceRecord
 end
 ```
 
-When both `Post` and `Comment` are registered in a portal, Plutonium automatically creates nested routes (`/posts/:post_id/comments`). The `associated_with` scope is automatically available for querying.
+When both `Post` and `Comment` are registered in a portal, Plutonium automatically creates nested routes (`/posts/:post_id/nested_comments`). Queries are automatically scoped to the parent via the association.
 
 See the [Nested Resources Guide](/guides/nested-resources) for details.
 

data/docs/reference/policy/index.md

@@ -36,12 +36,16 @@ Inside a policy, you have access to:
 | `user` | Current authenticated user (required) |
 | `record` | Resource being authorized |
 | `entity_scope` | Current scoped entity (for multi-tenancy) |
+| `parent` | Parent record for nested resources (nil if not nested) |
+| `parent_association` | Association name on parent (e.g., `:comments`) |
 
 ```ruby
 def update?
-  user          # => Current user
-  record        # => The Post instance
-  entity_scope  # => Organization for multi-tenant portals
+  user               # => Current user
+  record             # => The Post instance
+  entity_scope       # => Organization for multi-tenant portals
+  parent             # => Parent record (for nested routes)
+  parent_association # => :comments (association name)
 end
 ```
 
@@ -218,9 +222,29 @@ class PostPolicy < Plutonium::Resource::Policy
 end
 ```
 
-### With Entity Scoping
+### With Parent Scoping (Nested Resources)
 
-Call `super` to preserve automatic entity scoping for multi-tenancy:
+Call `super` to apply automatic parent scoping for nested resources:
+
+```ruby
+relation_scope do |relation|
+  relation = super(relation)  # Applies parent scoping automatically
+
+  if user.admin?
+    relation
+  else
+    relation.where(approved: true)
+  end
+end
+```
+
+**Parent scoping takes precedence over entity scoping.** When a parent is present:
+- For `has_many` associations: scopes via `parent.association_name`
+- For `has_one` associations: scopes via `where(foreign_key: parent.id)`
+
+### With Entity Scoping (Multi-tenancy)
+
+When no parent is present, `super` applies entity scoping:
 
 ```ruby
 relation_scope do |relation|
@@ -234,7 +258,54 @@ relation_scope do |relation|
 end
 ```
 
-The default `relation_scope` automatically applies `relation.associated_with(entity_scope)` when an entity scope is present.
+The default `relation_scope` automatically applies `relation.associated_with(entity_scope)` when an entity scope is present and no parent is set.
+
+### default_relation_scope is Required
+
+Plutonium verifies that `default_relation_scope` is called in every `relation_scope`. This prevents accidental multi-tenancy leaks when overriding scopes.
+
+```ruby
+# ❌ This will raise an error
+relation_scope do |relation|
+  relation.where(published: true)  # Missing default_relation_scope!
+end
+
+# ✅ Correct - call default_relation_scope
+relation_scope do |relation|
+  default_relation_scope(relation).where(published: true)
+end
+
+# ✅ Also correct - super calls default_relation_scope
+relation_scope do |relation|
+  super(relation).where(published: true)
+end
+```
+
+When overriding an inherited scope:
+
+```ruby
+class AdminPostPolicy < PostPolicy
+  relation_scope do |relation|
+    # Replace inherited scope but keep Plutonium's parent/entity scoping
+    default_relation_scope(relation)
+  end
+end
+```
+
+This method applies parent scoping (for nested resources) or entity scoping (for multi-tenancy) directly, bypassing any inherited scope customizations.
+
+### Skipping Default Scoping
+
+If you intentionally need to bypass scoping, call `skip_default_relation_scope!`:
+
+```ruby
+relation_scope do |relation|
+  skip_default_relation_scope!
+  relation  # No parent/entity scoping applied
+end
+```
+
+This should be rare - consider using a separate portal with different scoping rules instead.
 
 ## Portal-Specific Policies
 

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.34.1)
+    plutonium (0.37.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 9.0)
@@ -11,7 +11,7 @@ PATH
       phlex-tabler_icons
       phlexi-display (>= 0.2.0)
       phlexi-field (>= 0.2.0)
-      phlexi-form (>= 0.10.0)
+      phlexi-form (>= 0.14.0)
       phlexi-menu (>= 0.4.0)
       phlexi-table (>= 0.2.0)
       rabl (~> 0.16.1)
@@ -230,7 +230,7 @@ GEM
       fiber-local
       phlex (~> 2.0)
       zeitwerk
-    phlexi-form (0.11.0)
+    phlexi-form (0.14.0)
       activesupport
       phlex (~> 2.0)
       phlexi-field (~> 0.2.0)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.34.1)
+    plutonium (0.37.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 9.0)
@@ -11,7 +11,7 @@ PATH
       phlex-tabler_icons
       phlexi-display (>= 0.2.0)
       phlexi-field (>= 0.2.0)
-      phlexi-form (>= 0.10.0)
+      phlexi-form (>= 0.14.0)
       phlexi-menu (>= 0.4.0)
       phlexi-table (>= 0.2.0)
       rabl (~> 0.16.1)
@@ -209,7 +209,7 @@ GEM
       fiber-local
       phlex (~> 2.0)
       zeitwerk
-    phlexi-form (0.11.0)
+    phlexi-form (0.14.0)
       activesupport
       phlex (~> 2.0)
       phlexi-field (~> 0.2.0)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.34.1)
+    plutonium (0.37.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 9.0)
@@ -11,7 +11,7 @@ PATH
       phlex-tabler_icons
       phlexi-display (>= 0.2.0)
       phlexi-field (>= 0.2.0)
-      phlexi-form (>= 0.10.0)
+      phlexi-form (>= 0.14.0)
       phlexi-menu (>= 0.4.0)
       phlexi-table (>= 0.2.0)
       rabl (~> 0.16.1)
@@ -211,7 +211,7 @@ GEM
       fiber-local
       phlex (~> 2.0)
       zeitwerk
-    phlexi-form (0.11.0)
+    phlexi-form (0.14.0)
       activesupport
       phlex (~> 2.0)
       phlexi-field (~> 0.2.0)