plutonium 0.34.1 → 0.35.0

data/docs/getting-started/tutorial/{07-customizing-ui.md → 08-customizing-ui.md}

@@ -1,4 +1,4 @@
-# Chapter 7: Customizing the UI
+# Chapter 8: Customizing the UI
 
 In this chapter, you'll customize forms, tables, and pages to create a polished interface.
 
@@ -12,7 +12,7 @@ Fields control how attributes appear in forms and displays. Plutonium auto-infer
 # packages/blogging/app/definitions/blogging/post_definition.rb
 class Blogging::PostDefinition < Blogging::ResourceDefinition
   # Rich text editor instead of plain textarea
-  field :body, as: :rich_text
+  field :body, as: :markdown
 
   # Select with predefined options
   input :status, as: :select, choices: %w[draft review published]
@@ -38,8 +38,8 @@ Columns are auto-inferred from your model. Only declare columns when customizing
 ### Column Configuration
 
 ```ruby
-# Custom label and sortable
-column :user, label: "Author", sortable: true
+# Custom label
+column :user, label: "Author"
 
 # Computed column with block
 column :comment_count do |post|
@@ -73,7 +73,7 @@ end
 
 # Predefined scopes (reference model scopes)
 scope :published, default: true  # Applied by default, uses Post.published
-scope :drafts                    # Uses Post.draft
+scope :drafts                    # Uses Post.drafts
 
 # Inline scope with block
 scope(:recent) { |scope| scope.where('created_at > ?', 1.week.ago) }
@@ -146,7 +146,7 @@ Control form layout using wrapper options in definitions:
 class Blogging::PostDefinition < Blogging::ResourceDefinition
   # Full-width fields
   input :title, wrapper: {class: "col-span-full"}
-  input :body, as: :rich_text, wrapper: {class: "col-span-full"}
+  input :body, as: :markdown, wrapper: {class: "col-span-full"}
 
   # Side-by-side fields (default is col-span-full)
   input :published_at, wrapper: {class: "col-span-1"}
@@ -244,11 +244,11 @@ Congratulations! You've built a complete blog application with:
 - Authorization with policies
 - Custom actions with Interactions
 - Nested resources
+- Multiple portals (Admin and Author)
 - Customized UI
 
 Continue exploring:
 - [Guides](/guides/) - Deep dives on specific topics
 - [Reference](/reference/) - Complete API documentation
-- [Cookbook](/cookbook/) - Real-world recipes
 
 Happy building with Plutonium!

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

@@ -21,7 +21,7 @@ A blog application with:
 ## Prerequisites
 
 - Ruby 3.2+
-- Rails 8.0+ (or 7.1+)
+- Rails 7.2+ (Rails 8 recommended)
 - Node.js 18+
 - PostgreSQL (or SQLite for development)
 
@@ -49,7 +49,10 @@ Create a "Publish" action using Interactions for business logic.
 ### [6. Nested Resources](./06-nested-resources)
 Add Comments as a nested resource under Posts.
 
-### [7. Customizing the UI](./07-customizing-ui)
+### [7. Creating an Author Portal](./07-author-portal)
+Create a second portal with different access levels for content authors.
+
+### [8. Customizing the UI](./08-customizing-ui)
 Customize forms, tables, and views to match your requirements.
 
 ## Getting Help

data/docs/guides/authorization.md

@@ -238,6 +238,39 @@ relation_scope do |relation|
 end
 ```
 
+## Controller & View Helpers
+
+These helpers are available in controllers and views for authorization checks.
+
+### authorized_resource_scope
+
+Get an authorized scope for a resource other than the current controller's resource. Useful in dashboards and custom views:
+
+```ruby
+# In a view or controller
+authorized_resource_scope(Post)                    # => Post.where(...)
+authorized_resource_scope(Post).count              # => 42
+authorized_resource_scope(Comment, relation: post.comments)
+```
+
+### policy_for
+
+Get the policy instance for any record:
+
+```ruby
+policy_for(@post)                    # => PostPolicy instance
+policy_for(@post).update?            # => true/false
+```
+
+### allowed_to?
+
+Check if an action is permitted:
+
+```ruby
+allowed_to?(:edit?, @post)           # => true/false
+allowed_to?(:create?, Post)          # => true/false
+```
+
 ## Portal-Specific Policies
 
 Override policies for specific portals:

data/docs/guides/creating-packages.md

@@ -23,7 +23,6 @@ rails g pu:pkg:package blogging
 packages/blogging/
 ├── app/
 │   ├── controllers/blogging/
-│   │   └── resource_controller.rb
 │   ├── definitions/blogging/
 │   │   └── resource_definition.rb
 │   ├── interactions/blogging/
@@ -87,8 +86,7 @@ packages/admin_portal/
 │   ├── controllers/admin_portal/
 │   │   ├── concerns/controller.rb
 │   │   ├── dashboard_controller.rb
-│   │   ├── plutonium_controller.rb
-│   │   └── resource_controller.rb
+│   │   └── plutonium_controller.rb
 │   ├── definitions/admin_portal/
 │   │   └── resource_definition.rb
 │   ├── policies/admin_portal/
@@ -348,30 +346,28 @@ end
 
 ```ruby
 # packages/admin_portal/app/controllers/admin_portal/posts_controller.rb
-module AdminPortal
-  class PostsController < ResourceController
-    private
+class AdminPortal::PostsController < ::PostsController
+  include AdminPortal::Concerns::Controller
 
-    def preferred_action_after_submit
-      "index"
-    end
+  private
+
+  def preferred_action_after_submit
+    "index"
   end
 end
 ```
 
 ## Controller Hierarchy
 
+Portal controllers inherit from the feature package's controller:
+
 ```
-::PlutoniumController (app-wide base)
-    ↓
-::ResourceController (resource handling)
-    ↓
-AdminPortal::ResourceController (portal base)
+::PostsController (feature package controller)
     ↓
-AdminPortal::PostsController (resource-specific)
+AdminPortal::PostsController (portal-specific, includes Concerns::Controller)
 ```
 
-Controllers are auto-created if not defined.
+Controllers are auto-created if not defined. When accessing a portal resource controller, Plutonium dynamically creates it by inheriting from the feature package's controller and including the portal's controller concern.
 
 ## Related
 

data/docs/guides/custom-actions.md

@@ -218,6 +218,10 @@ action :export, interaction: ExportInteraction, resource_action: true
 
 ## Bulk Action Interaction
 
+Bulk actions operate on multiple selected records. When a definition has bulk actions, the resource table automatically shows:
+- **Selection checkboxes** in each row
+- **Bulk actions toolbar** that appears when records are selected
+
 ```ruby
 class BulkPublishInteraction < ResourceInteraction
   presents label: "Publish Selected",
@@ -240,6 +244,34 @@ class BulkPublishInteraction < ResourceInteraction
 end
 ```
 
+Register in your definition:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  action :bulk_publish, interaction: BulkPublishInteraction
+  # bulk_action: true is automatically inferred from `resources` attribute
+end
+```
+
+Add the policy method (checked per-record):
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def bulk_publish?
+    # Can use record attributes - checked for each selected record
+    user.admin? || record.author == user
+  end
+end
+```
+
+::: tip Bulk Action Authorization
+Bulk actions use **per-record authorization**:
+- The policy method (e.g., `bulk_publish?`) is checked for **each selected record** - you can use `record` attributes
+- Backend rejects the entire request if any record fails authorization
+- UI only shows actions that **all** selected records support (buttons hide dynamically as you select)
+- Records are fetched from `current_authorized_scope` - only accessible records can be selected
+:::
+
 ## Resource Action (No Record)
 
 ```ruby
@@ -307,6 +339,10 @@ action :bulk_delete,
 
 ### Success
 
+::: tip Automatic Redirect
+On success, the controller automatically redirects to the resource. You can use `with_redirect_response` if you want a **different** destination.
+:::
+
 ```ruby
 def execute
   # ... do work ...

data/docs/guides/search-filtering.md

@@ -6,7 +6,7 @@ This guide covers implementing search, filters, scopes, and sorting.
 
 Plutonium provides built-in support for:
 - **Search** - Full-text search across fields
-- **Filters** - Input filters for specific fields
+- **Filters** - Input filters for specific fields (dropdown panel)
 - **Scopes** - Predefined query shortcuts (quick filter buttons)
 - **Sorting** - Column-based ordering
 
@@ -68,33 +68,28 @@ end
 
 ## Filters
 
-Filters provide UI controls for narrowing results.
+Plutonium provides **6 built-in filter types**. Use shorthand symbols or full class names.
 
 ### Text Filter
 
-The built-in `Text` filter supports various predicates:
+String/text filtering with pattern matching:
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  # Exact match
-  filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
+  # Shorthand (recommended)
+  filter :title, with: :text, predicate: :contains
+  filter :status, with: :text, predicate: :eq
 
-  # Contains (LIKE %value%)
-  filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
-
-  # Starts with
+  # Full class name also works
   filter :slug, with: Plutonium::Query::Filters::Text, predicate: :starts_with
-
-  # Ends with
-  filter :email, with: Plutonium::Query::Filters::Text, predicate: :ends_with
 end
 ```
 
-### Available Predicates
+#### Available Predicates
 
 | Predicate | SQL | Description |
 |-----------|-----|-------------|
-| `:eq` | `= value` | Exact match |
+| `:eq` | `= value` | Exact match (default) |
 | `:not_eq` | `!= value` | Not equal |
 | `:contains` | `LIKE %value%` | Contains text |
 | `:not_contains` | `NOT LIKE %value%` | Does not contain |
@@ -103,40 +98,120 @@ end
 | `:matches` | `LIKE value` | Pattern match (`*` becomes `%`) |
 | `:not_matches` | `NOT LIKE value` | Does not match pattern |
 
-### Custom Filter with Lambda
+### Boolean Filter
+
+True/false filtering for boolean columns:
 
 ```ruby
-filter :published, with: ->(scope, value) {
-  value == "true" ? scope.where.not(published_at: nil) : scope.where(published_at: nil)
-}
-
-filter :has_comments, with: ->(scope, value) {
-  if value == "true"
-    scope.joins(:comments).distinct
-  else
-    scope.left_joins(:comments).where(comments: { id: nil })
-  end
-}
+# Basic
+filter :active, with: :boolean
+
+# Custom labels
+filter :published, with: :boolean, true_label: "Published", false_label: "Draft"
+```
+
+Renders a select dropdown with "All", true label ("Yes"), and false label ("No").
+
+### Date Filter
+
+Single date filtering with comparison predicates:
+
+```ruby
+filter :created_at, with: :date, predicate: :gteq  # On or after
+filter :due_date, with: :date, predicate: :lt      # Before
+filter :published_at, with: :date, predicate: :eq  # On exact date
+```
+
+#### Available Predicates
+
+| Predicate | Description |
+|-----------|-------------|
+| `:eq` | On this date (default) |
+| `:not_eq` | Not on this date |
+| `:lt` | Before date |
+| `:lteq` | On or before date |
+| `:gt` | After date |
+| `:gteq` | On or after date |
+
+### Date Range Filter
+
+Filter between two dates (from/to):
+
+```ruby
+# Basic
+filter :created_at, with: :date_range
+
+# Custom labels
+filter :published_at, with: :date_range,
+  from_label: "Published from",
+  to_label: "Published to"
 ```
 
+Renders two date pickers. Both are optional - users can filter with just "from" or just "to".
+
+### Select Filter
+
+Filter from predefined choices:
+
+```ruby
+# Static choices (array)
+filter :status, with: :select, choices: %w[draft published archived]
+
+# Dynamic choices (proc)
+filter :category, with: :select, choices: -> { Category.pluck(:name) }
+
+# Multiple selection
+filter :tags, with: :select, choices: %w[ruby rails js], multiple: true
+```
+
+### Association Filter
+
+Filter by associated record:
+
+```ruby
+# Basic - infers Category class from :category key
+filter :category, with: :association
+
+# Explicit class
+filter :author, with: :association, class_name: User
+
+# Multiple selection
+filter :tags, with: :association, class_name: Tag, multiple: true
+```
+
+Renders a resource select dropdown. Converts filter key to foreign key (`:category` -> `:category_id`).
+
+### Filter Summary Table
+
+| Type | Symbol | Input Params | Options |
+|------|--------|--------------|---------|
+| Text | `:text` | `query` | `predicate:` |
+| Boolean | `:boolean` | `value` | `true_label:`, `false_label:` |
+| Date | `:date` | `value` | `predicate:` |
+| Date Range | `:date_range` | `from`, `to` | `from_label:`, `to_label:` |
+| Select | `:select` | `value` | `choices:`, `multiple:` |
+| Association | `:association` | `value` | `class_name:`, `multiple:` |
+
 ### Custom Filter Class
 
 ```ruby
-class DateRangeFilter < Plutonium::Query::Filter
-  def apply(scope, start_date: nil, end_date: nil)
-    scope = scope.where("#{key} >= ?", start_date.beginning_of_day) if start_date.present?
-    scope = scope.where("#{key} <= ?", end_date.end_of_day) if end_date.present?
+class PriceRangeFilter < Plutonium::Query::Filter
+  def apply(scope, min: nil, max: nil)
+    scope = scope.where("price >= ?", min) if min.present?
+    scope = scope.where("price <= ?", max) if max.present?
     scope
   end
 
   def customize_inputs
-    input :start_date, as: :date
-    input :end_date, as: :date
+    input :min, as: :number
+    input :max, as: :number
+    field :min, placeholder: "Min price..."
+    field :max, placeholder: "Max price..."
   end
 end
 
 # Use in definition
-filter :created_at, with: DateRangeFilter
+filter :price, with: PriceRangeFilter
 ```
 
 ## Scopes
@@ -224,7 +299,9 @@ Query parameters are structured under `q`:
 
 ```
 /posts?q[search]=rails
-/posts?q[status][query]=published
+/posts?q[title][query]=widget
+/posts?q[status][value]=published
+/posts?q[created_at][from]=2024-01-01&q[created_at][to]=2024-12-31
 /posts?q[scope]=recent
 /posts?q[sort_fields][]=created_at&q[sort_directions][created_at]=desc
 ```
@@ -232,28 +309,30 @@ Query parameters are structured under `q`:
 ## Complete Example
 
 ```ruby
-class PostDefinition < ResourceDefinition
+class ProductDefinition < ResourceDefinition
   # Full-text search
   search do |scope, query|
     scope.where(
-      "title ILIKE :q OR content ILIKE :q",
+      "name ILIKE :q OR description ILIKE :q",
       q: "%#{query}%"
     )
   end
 
   # Filters
-  filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
-  filter :category, with: Plutonium::Query::Filters::Text, predicate: :eq
-  filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
+  filter :name, with: :text, predicate: :contains
+  filter :status, with: :select, choices: %w[draft active discontinued]
+  filter :featured, with: :boolean
+  filter :created_at, with: :date_range
+  filter :price, with: :date, predicate: :gteq
+  filter :category, with: :association
 
   # Quick scopes (reference model scopes)
-  scope :published
-  scope :draft
+  scope :active, default: true
   scope :featured
   scope(:recent) { |scope| scope.where("created_at > ?", 1.week.ago) }
 
   # Sortable columns
-  sorts :title, :created_at, :view_count, :published_at
+  sorts :name, :price, :created_at
 
   # Default: newest first
   default_sort :created_at, :desc