plutonium 0.24.0 → 0.24.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38e9b4259eace82de069a8676149a0aee950555d3b8f9040e40d2f96d84408af
-  data.tar.gz: 0cffa959583789f1450d2ba401ea9b1bfb78b0a348394a31e692682b4135648f
+  metadata.gz: cb793ad2d24a4aef3c7a5c46146260b019e6ab1af1e82a23c110379f96b51df6
+  data.tar.gz: 3926d88a01fa0a9ec45b2c072b0c8112e058082520fb4d2019f765a8cf2a97a3
 SHA512:
-  metadata.gz: f6c4136e5b5d8fe44e790475b93df8d38a210f1b14f9e49913a8784af05b838475f14f2cf9596c9a012377e6fae78c439f04f034c7017c5984c9c95e58d37cd0
-  data.tar.gz: 47183a92cd658a41d9d966fc803ef0a30635266e97e774e27115ae8122ef82568219b196e29388959078be8319f4b5bf538197a849ca0d75833385fa2ce77657
+  metadata.gz: 4bf56145b9fc26fe50d167bfdffd347488c4be2d7a32c985d698ca4c24e40fc98cfc26e3a3c5cf88fca7dbf8de934f4c4974e8d394b347918c1f1d962484ace6
+  data.tar.gz: dacc135a569a2c5ec92134e7cf2670948680622c529514e2ddb996318e4e120330081ea8fd122b6c4dd9e29e3e6c838dcb037ca0939f65e16a43c73f2f50851e

data/docs/modules/definition.md

@@ -214,17 +214,26 @@ To create forms that dynamically show/hide inputs based on other form values, pa
 
 Plutonium offers three main approaches for rendering fields in a definition. Choose the one that best fits your needs for clarity, flexibility, and control.
 
+**Quick Reference:**
+- **`as: :symbol`** - Use built-in components for input and display (e.g., `:rich_text`, `:date`, `:markdown`)
+- **`as: ComponentClass`** - Use custom component classes for input and display (new feature)
+- **Block syntax** - Use for conditional logic and custom builder method calls
+- **`as: :phlexi_tag`** - Advanced inline rendering with maximum flexibility (display only)
+
 #### 1. The `as:` Option (Recommended)
 
-The `as:` option is the simplest and most common way to specify a rendering component for an `input` or `display` declaration. It's ideal for using standard built-in components or overriding auto-detected types.
+The `as:` option is the simplest and most common way to specify a rendering component for both `input` and `display` declarations. It's ideal for using standard built-in components or overriding auto-detected types.
+
+**New Feature**: You can now pass a component class directly to the `as:` option for custom rendering in both input and display contexts.
 
 **Use When:**
-- Using standard or enhanced built-in components.
+- Using standard or enhanced built-in components for input or display.
 - You want clean, readable code with minimal boilerplate.
-- Overriding an auto-detected type (e.g., `text` to `rich_text`).
+- Overriding an auto-detected type (e.g., `text` to `rich_text` for input, or `text` to `markdown` for display).
+- Using custom component classes for rendering.
 
 ::: code-group
-```ruby [Input Fields]
+```ruby [Standard Input Fields]
 # Simple and concise overrides
 class PostDefinition < Plutonium::Resource::Definition
   input :content, as: :rich_text
@@ -235,7 +244,19 @@ class PostDefinition < Plutonium::Resource::Definition
   input :email, as: :email, placeholder: "Enter email"
 end
 ```
-```ruby [Display Fields]
+```ruby [Custom Component Classes]
+# Using custom component classes
+class PostDefinition < Plutonium::Resource::Definition
+  # Pass component class to input
+  input :color_picker, as: ColorPickerComponent
+  input :custom_widget, as: MyCustomInputComponent
+
+  # Pass component class to display
+  display :status_badge, as: StatusBadgeComponent
+  display :chart, as: ChartComponent
+end
+```
+```ruby [Standard Display Fields]
 # Simple and concise overrides
 class PostDefinition < Plutonium::Resource::Definition
   display :content, as: :markdown
@@ -252,25 +273,34 @@ end
 
 The block syntax offers more control over rendering, allowing for custom components, complex layouts, and conditional logic. The block receives a `field` object that you can use to render custom output.
 
+**Important for Input Blocks**: When using blocks with `input` declarations, you can only use existing form builder methods (like `f.date_tag`, `f.text_tag`, etc.). You cannot return arbitrary components because the form system requires inputs to be registered internally.
+
 **Use When:**
-- Integrating custom-built Phlex or ViewComponent components.
-- Building complex layouts with multiple components or custom HTML.
+- Integrating custom-built Phlex or ViewComponent components (for `display` only).
+- Building complex layouts with multiple components or custom HTML (for `display` only).
 - You need conditional logic to determine which component to render.
+- You need to call specific form builder methods with custom logic (for `input`).
 
 ::: code-group
 ```ruby [Custom Display Components]
-# Custom display component
+# Custom display component - can return any component
 display :chart_data do |field|
   ChartComponent.new(data: field.value, type: :bar)
 end
 ```
-```ruby [Custom Input Components]
-# Custom input component
-input :color do |field|
-  ColorPickerComponent.new(field)
+```ruby [Custom Input with Builder Methods]
+# Custom input - can only use form builder methods
+input :birth_date do |f|
+  # Can use builder methods with custom logic
+  case object.age_category
+  when 'adult'
+    f.date_tag(min: 18.years.ago.to_date)
+  when 'minor'
+    f.date_tag(max: 18.years.ago.to_date)
+  else
+    f.date_tag
+  end
 end
-```
-
 ```
 ```ruby [Conditional Rendering]
 # Conditional display based on value

data/docs/modules/form.md

@@ -124,6 +124,36 @@ end
 
 Plutonium replaces standard form inputs with enhanced versions that provide a modern user experience.
 
+### Input Block Syntax
+
+Input blocks provide additional flexibility for custom logic while ensuring proper form integration. **Important**: Input blocks can only use existing form builder methods (like `date_tag`, `text_tag`, etc.) because the form system requires inputs to be registered internally.
+
+::: code-group
+```ruby [Input Block Example]
+# Valid: Using form builder methods with custom logic
+input :birth_date do |f|
+  case object.age_category
+  when 'adult'
+    f.date_tag(min: 18.years.ago.to_date)
+  when 'minor'
+    f.date_tag(max: 18.years.ago.to_date)
+  else
+    f.date_tag
+  end
+end
+```
+
+```ruby [Custom Component Classes]
+# New: Pass component classes directly to as: option
+# Works for both input and display
+input :color_picker, as: ColorPickerComponent
+input :custom_slider, as: RangeSliderComponent
+
+display :status_badge, as: StatusBadgeComponent
+display :progress_chart, as: ProgressChartComponent
+```
+:::
+
 ### Markdown Editor (Easymde)
 
 For rich text content, Plutonium integrates a client-side markdown editor based on [EasyMDE](https://github.com/Ionaru/easy-markdown-editor). It's automatically used for `rich_text` fields (like ActionText) and provides a live preview.

data/docs/public/plutonium.mdc

@@ -121,6 +121,20 @@ class PostDefinition < Plutonium::Resource::Definition
   input :content, as: :rich_text
   input :category, as: :select, collection: %w[Tech Business Lifestyle]
 
+  # New: Custom component classes
+  input :color_picker, as: ColorPickerComponent
+  display :status_badge, as: StatusBadgeComponent
+
+  # Input blocks for custom logic (must use form builder methods)
+  input :birth_date do |f|
+    case object.age_category
+    when 'adult'
+      f.date_tag(min: 18.years.ago.to_date)
+    else
+      f.date_tag
+    end
+  end
+
   # Conditional inputs (for forms only)
   # Use for COSMETIC/STATE-BASED logic only, NOT authorization (use policies for that)
   input :debug_info, condition: -> { Rails.env.development? }
@@ -467,201 +481,72 @@ include Plutonium::Auth::Rodauth(:admin)    # For admin authentication
 include Plutonium::Auth::Public             # For public access
 ```
 
-## Multi-Tenancy & Entity Scoping
-
-### Path-Based Scoping
-```ruby
-# Portal engine
-scope_to_entity Organization, strategy: :path
-
-# Generates routes like: /organizations/:organization_id/posts
-# Automatically scopes all queries to the organization
-```
+## Routing & Custom Routes
 
-### Database Associations for Scoping
+### Resource Registration
 ```ruby
-# Direct association (auto-detected)
-class Post < ApplicationRecord
-  belongs_to :organization
-end
-
-# Indirect association (auto-detected)
-class Post < ApplicationRecord
-  belongs_to :author, class_name: 'User'
-  has_one :organization, through: :author
-end
-
-# Custom scope (manual)
-class Comment < ApplicationRecord
-  belongs_to :post
+# Basic resource registration
+register_resource Post
+
+# Custom routes with member/collection actions
+register_resource Post do
+  member do
+    get :publish      # /posts/1/publish
+    post :archive     # /posts/1/archive
+  end
 
-  scope :associated_with_organization, ->(organization) do
-    joins(post: :author).where(users: { organization_id: organization.id })
+  collection do
+    get :search       # /posts/search
   end
 end
 ```
 
-## Query Objects & Filtering
+### Common Routing Errors
 
-### Automatic Query Handling
-Controllers automatically handle:
-- Search: `?q[search]=rails`
-- Filters: `?q[published]=true`
-- Sorting: `?q[sort_fields][]=created_at&q[sort_directions][created_at]=desc`
-- Scopes: `?q[scope]=published`
+#### "Unresolvable Association" Error
+When adding custom routes inside `register_resource` blocks, Plutonium may interpret them as nested resources and fail with:
+```
+RuntimeError (Could not resolve the association between 'Model' and 'Model')
+```
 
-### Custom Query Objects
+**Problem**: Routes like this create nested resource interpretation:
 ```ruby
-query_object = Plutonium::Resource::QueryObject.new(Post, params[:q] || {}, request.path) do |query|
-  # Custom search
-  query.define_search proc { |scope, search:|
-    scope.joins(:author, :tags)
-         .where("posts.title ILIKE :search OR users.name ILIKE :search", search: "%#{search}%")
-         .distinct
-  }
-
-  # Custom filter
-  query.define_filter :date_range, proc { |scope, start_date:, end_date:|
-    scope.where(created_at: start_date.beginning_of_day..end_date.end_of_day)
-  }
-
-  # Custom sorter
-  query.define_sorter :author_name, proc { |scope, direction:|
-    scope.joins(:author).order("users.name #{direction}")
-  }
+register_resource ::UniversalFlow::Definition do
+  get "editor", to: "universal_flow/definitions#editor"
 end
 ```
 
-## UI Components & Theming
-
-### Component Architecture
-Built on Phlex, components inherit from `Plutonium::UI::Component::Base`:
+**Solutions**:
 
+1. **Add custom scope to model (Recommended)**:
 ```ruby
-class CustomComponent < Plutonium::UI::Component::Base
-  def initialize(title:, content: nil)
-    @title = title
-    @content = content
-  end
-
-  def view_template
-    div(class: "custom-component") do
-      h2(class: "text-xl font-bold") { @title }
-      div(class: "content") { @content } if @content
-    end
-  end
+class UniversalFlow::Definition < ApplicationRecord
+  scope :associated_with_universal_flow_definition, ->(universal_flow_definition) {
+    all # or specific logic for your use case
+  }
 end
 ```
 
-### Layout Customization
+2. **Use member/collection routes**:
 ```ruby
-# Custom page classes in definitions
-class PostDefinition < Plutonium::Resource::Definition
-  class ShowPage < Plutonium::UI::Page::Show
-    def render_content
-      # Custom show page rendering
-      super
-    end
+register_resource ::UniversalFlow::Definition do
+  member do
+    get :editor
   end
 end
 ```
 
-## Configuration
-
-### Main Configuration
+3. **Create separate controller**:
 ```ruby
-# config/initializers/plutonium.rb
-Plutonium.configure do |config|
-  config.load_defaults 1.0
-
-  # Development settings
-  config.development = Rails.env.development?
-  config.cache_discovery = !Rails.env.development?
-  config.enable_hotreload = Rails.env.development?
-
-  # Assets
-  config.assets.logo = "custom_logo.png"
-  config.assets.stylesheet = "custom_theme.css"
-  config.assets.script = "custom_plutonium.js"
-  config.assets.favicon = "custom_favicon.ico"
+# In routes file
+get 'universal_flow/editor/:id', to: 'universal_flow/editor#show'
+
+# Create dedicated controller
+class UniversalFlow::EditorController < CustomerPortal::ResourceController
+  def show
+    @definition = UniversalFlow::Definition.find(params[:id])
+    authorize_current! @definition
+    # ... custom logic
+  end
 end
 ```
-
-## Generator Commands
-
-### Core Setup
-```bash
-# Install Plutonium in existing app
-bin/rails app:template LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
-rails generate pu:core:install
-
-# Install authentication
-rails generate pu:rodauth:install
-rails generate pu:rodauth:account user
-```
-
-### Package Creation
-```bash
-# Create feature package
-rails generate pu:pkg:package blogging
-
-# Create portal package
-rails generate pu:pkg:portal admin
-```
-
-### Resource Management
-```bash
-# Full resource scaffold
-rails generate pu:res:scaffold Post user:belongs_to title:string content:text
-
-# Individual resource components
-rails generate pu:res:model Post title:string content:text
-rails generate pu:res:definition Post
-rails generate pu:res:policy Post
-```
-
-## Best Practices
-
-### Resource Design
-1. Keep models focused on data and basic validations
-2. Use definitions for UI configuration, not business logic
-3. Implement complex business logic in interactions
-4. Use policies for all authorization logic
-5. Leverage scopes for common queries
-
-### Package Organization
-1. Create feature packages for domain logic
-2. Use portal packages for different user interfaces
-3. Keep packages focused and cohesive
-4. Namespace everything properly to avoid conflicts
-
-### Security
-1. Always define explicit permissions in policies
-2. Use secure defaults (deny by default)
-3. Implement proper entity scoping for multi-tenancy
-4. Validate all user inputs in interactions
-5. Use CSRF protection and implement rate limiting
-
-### Performance
-1. Use `includes` and `joins` in relation scopes
-2. Add database indexes for filtered and sorted fields
-3. Implement caching where appropriate
-4. Use background jobs for heavy operations
-5. Monitor N+1 queries with tools like Prosopite
-
-### Code Organization
-1. Follow Rails naming conventions
-2. Keep controllers thin - use interactions for business logic
-3. Use consistent patterns across resources
-4. Write comprehensive tests for policies and interactions
-5. Document complex business logic
-
-### Development Workflow
-1. Start with resource scaffolding for rapid prototyping
-2. Customize definitions for UI requirements
-3. Implement business logic through interactions
-4. Add proper authorization with policies
-5. Create appropriate packages for organization
-6. Set up portals for different user types
-
-This comprehensive guide should enable you to build robust, maintainable Plutonium applications following the framework's conventions and best practices.

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

@@ -92,7 +92,11 @@ module Plutonium
             tag_attributes = display_options.except(:wrapper, :as, :condition)
             tag_block = display_definition[:block] || ->(f) {
               tag ||= f.inferred_field_component
-              f.send(:"#{tag}_tag", **tag_attributes)
+              if tag.is_a?(Class)
+                f.send :create_component, tag, tag.name.demodulize.underscore.sub(/component$/, "").to_sym
+              else
+                f.send(:"#{tag}_tag", **tag_attributes)
+              end
             }
 
             wrapper_options = display_options[:wrapper] || {}

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

@@ -68,7 +68,11 @@ module Plutonium
           end
           tag_block = input_definition[:block] || ->(f) do
             tag ||= f.inferred_field_component
-            f.send(:"#{tag}_tag", **tag_attributes)
+            if tag.is_a?(Class)
+              f.send :create_component, tag, tag.name.demodulize.underscore.sub(/component$/, "").to_sym
+            else
+              f.send(:"#{tag}_tag", **tag_attributes)
+            end
           end
 
           field_options = field_options.except(:as, :condition)

data/lib/plutonium/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plutonium
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.24.1
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-25 00:00:00.000000000 Z
+date: 2025-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk