plutonium 0.14.0 → 0.15.0.pre.rc1

data/lib/plutonium/definition/defineable_props.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Definition
+    # Module for handling defineable properties in Plutonium definitions
+    #
+    # @example
+    #   class MyDefinition
+    #     include DefineableProperties
+    #
+    #     defineable_property :field
+    #     defineable_property :input
+    #     defineable_property :filter
+    #     defineable_property :scope
+    #     defineable_property :sorter
+    #   end
+    module DefineableProps
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_defineable_props_store, instance_accessor: false, instance_predicate: false, default: []
+      end
+
+      class_methods do
+        def defineable_props(*property_names)
+          property_names.each { |name| defineable_prop(name) }
+        end
+
+        # Defines a new property type for the class
+        #
+        # @param property_name [Symbol] The name of the property to define
+        # @return [void]
+        def defineable_prop(property_name)
+          property_plural = property_name.to_s.pluralize.to_sym
+          property_getter = :"defined_#{property_plural}"
+          self._defineable_props_store += [property_plural]
+
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def self.#{property_name}(name, **options, &block)
+              #{property_getter}[name] = { options:, block:}.compact
+            end
+
+            def self.#{property_getter}
+              @#{property_getter} ||= {}
+            end
+
+            def #{property_name}(name, **options, &block)
+              instance_#{property_getter}[name] = { options:, block:}.compact
+            end
+
+            def #{property_getter}
+              @merged_#{property_getter} ||= begin
+                customize_#{property_plural}
+                merged = {}
+                self.class.#{property_getter}.each do |name, data|
+                  merged[name] = {
+                    options: data[:options].dup,
+                    block: data[:block]
+                  }.compact
+                end
+                instance_#{property_getter}.each do |name, data|
+                  if merged.key?(name)
+                    merged[name][:options].merge!(data[:options])
+                    merged[name][:block] = data[:block] if data[:block]
+                  else
+                    merged[name] = data
+                  end
+                  # merged[name].compact!
+                end
+                merged
+              end
+            end
+
+            def customize_#{property_plural}
+              # Override in subclass to add or modify #{property_plural}
+            end
+
+            private
+
+            def instance_#{property_getter}
+              @instance_#{property_getter} ||= {}
+            end
+          RUBY
+        end
+
+        # Handles inheritance by duplicating class-level collections
+        def inherited(subclass)
+          super
+          _defineable_props_store.each do |property|
+            subclass.instance_variable_set(:"@defined_#{property}", instance_variable_get(:"@defined_#{property}")&.deep_dup || {})
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/definition/search.rb

@@ -0,0 +1,21 @@
+module Plutonium
+  module Definition
+    module Search
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_search_definition, instance_accessor: false, instance_predicate: false
+      end
+
+      def search_definition
+        self.class._search_definition
+      end
+
+      class_methods do
+        def search(&block)
+          self._search_definition = block
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/engine/validator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Engine
+    module Validator
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Validates that the current engine supports Plutonium features.
+        #
+        # @raise [ArgumentError] If the engine doesn't include Plutonium::Engine.
+        # @return [void]
+        def validate_engine!(engine)
+          return if supported_engine?(engine)
+
+          # TODO: make the error link to documentation on how to ensure that your engine is supported
+          raise ArgumentError, "#{engine} must include Plutonium::Engine to call register resources"
+        end
+
+        # Checks if the current engine supports Plutonium features.
+        #
+        # @return [Boolean] True if the engine includes Plutonium::Engine, false otherwise.
+        def supported_engine?(engine)
+          # TODO: fix constant being out of sync after reload during development
+          Plutonium.configuration.development? ? engine.respond_to?(:dom_id) : engine.include?(Plutonium::Engine)
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/engine.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Engine
+    extend ActiveSupport::Concern
+
+    class_methods do
+      attr_reader :scoped_entity_class, :scoped_entity_strategy, :scoped_entity_param_key
+
+      def scope_to_entity(entity_class, strategy: :path, param_key: nil)
+        @scoped_entity_class = entity_class
+        @scoped_entity_strategy = strategy
+        @scoped_entity_param_key = param_key || entity_class.model_name.singular_route_key.to_sym
+      end
+
+      def scoped_to_entity?
+        scoped_entity_class.present?
+      end
+
+      def dom_id
+        module_parent_name.underscore.dasherize
+      end
+    end
+  end
+end

data/lib/plutonium/helpers/assets_helper.rb

@@ -1,41 +1,94 @@
+# frozen_string_literal: true
+
 module Plutonium
   module Helpers
+    # Helper module for managing asset-related functionality
     module AssetsHelper
+      # Generate a stylesheet tag for the resource
+      #
+      # @return [ActiveSupport::SafeBuffer] HTML stylesheet link tag
       def resource_stylesheet_tag
-        url = if Plutonium.development?
-          filename = JSON.parse(File.read(Plutonium.root.join("src", "build", "css.manifest")))["plutonium.css"]
-          "/build/#{filename}"
-        else
-          resource_stylesheet_asset
-        end
-        stylesheet_link_tag url, "data-turbo-track": "reload"
+        url = resource_asset_url_for(:css, resource_stylesheet_asset)
+        stylesheet_link_tag(url, "data-turbo-track": "reload")
       end
 
+      # Generate a script tag for the resource
+      #
+      # @return [ActiveSupport::SafeBuffer] HTML script tag
       def resource_script_tag
-        url = if Plutonium.development?
-          filename = JSON.parse(File.read(Plutonium.root.join("src", "build", "js.manifest")))["plutonium.js"]
-          "/build/#{filename}"
-        else
-          resource_script_asset
-        end
-        javascript_include_tag url, "data-turbo-track": "reload", type: "module"
+        url = resource_asset_url_for(:js, resource_script_asset)
+        javascript_include_tag(url, "data-turbo-track": "reload", type: "module")
       end
 
+      # Generate a favicon link tag
+      #
+      # @return [ActiveSupport::SafeBuffer] HTML favicon link tag
       def resource_favicon_tag
-        favicon_link_tag resource_favicon_asset
+        favicon_link_tag(resource_favicon_asset)
       end
 
+      # Generate an image tag for the logo
+      #
+      # @param classname [String] CSS class name for the image tag
+      # @return [ActiveSupport::SafeBuffer] HTML image tag
       def resource_logo_tag(classname:)
-        image_tag resource_logo_asset, class: classname
+        image_tag(resource_logo_asset, class: classname)
       end
 
-      def resource_logo_asset = Rails.application.config.plutonium.assets.logo
+      # Get the logo asset path
+      #
+      # @return [String] path to the logo asset
+      def resource_logo_asset
+        Plutonium.configuration.assets.logo
+      end
 
-      def resource_stylesheet_asset = Rails.application.config.plutonium.assets.stylesheet
+      # Get the stylesheet asset path
+      #
+      # @return [String] path to the stylesheet asset
+      def resource_stylesheet_asset
+        Plutonium.configuration.assets.stylesheet
+      end
 
-      def resource_script_asset = Rails.application.config.plutonium.assets.script
+      # Get the script asset path
+      #
+      # @return [String] path to the script asset
+      def resource_script_asset
+        Plutonium.configuration.assets.script
+      end
 
-      def resource_favicon_asset = Rails.application.config.plutonium.assets.favicon
+      # Get the favicon asset path
+      #
+      # @return [String] path to the favicon asset
+      def resource_favicon_asset
+        Plutonium.configuration.assets.favicon
+      end
+
+      private
+
+      # Generate the appropriate asset URL based on the environment
+      #
+      # @param type [Symbol] asset type (:css or :js)
+      # @param fallback [String] fallback asset path
+      # @return [String] asset URL
+      def resource_asset_url_for(type, fallback)
+        if Plutonium.configuration.development?
+          resource_development_asset_url(type)
+        else
+          fallback
+        end
+      end
+
+      # Generate the asset URL for development environment
+      #
+      # @param type [Symbol] asset type (:css or :js)
+      # @return [String] asset URL for development
+      def resource_development_asset_url(type)
+        manifest_file = (type == :css) ? "css.manifest" : "js.manifest"
+        asset_key = (type == :css) ? "plutonium.css" : "plutonium.js"
+
+        filename = JSON.parse(File.read(Plutonium.root.join("src", "build", manifest_file)))[asset_key]
+        "/build/#{filename}"
+      end
     end
   end
 end

data/lib/plutonium/helpers/form_helper.rb

@@ -1,5 +1,3 @@
-require "view_component/form"
-
 module Plutonium
   module Helpers
     module FormHelper
@@ -23,7 +21,7 @@ module Plutonium
 
       def token_tag(...)
         # needed to workaround https://github.com/tailwindlabs/tailwindcss/issues/3350
-        super(...).sub(" />", " hidden />").html_safe
+        super.sub(" />", " hidden />").html_safe
       end
 
       private

data/lib/plutonium/interaction/README.md

@@ -0,0 +1,369 @@
+# Interactions
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Key Concepts](#key-concepts)
+3. [Core Components](#core-components)
+4. [Setup](#setup)
+5. [Usage](#usage)
+6. [Best Practices](#best-practices)
+7. [Testing](#testing)
+8. [Advanced Features](#advanced-features)
+9. [Examples](#examples)
+
+## Introduction
+
+Interactions allows us to leverage an architectural approach that focuses on organizing code around business actions or user interactions.
+It builds upon the traditional MVC pattern by introducing additional layers that encapsulate business logic and improve separation of concerns.
+
+### Key Benefits
+
+- Clear separation of business logic from controllers
+- Improved testability of business operations
+- Consistent handling of success and failure cases
+- Flexible and expressive way to chain operations
+- Enhanced maintainability and readability of complex business processes
+- Improved code organization and discoverability of business logic
+
+## Key Concepts
+
+### Interactions
+
+Interactions are the core of this pattern. They represent specific use cases or business operations in your application. Each interaction is responsible for a single, well-defined task.
+Interactions encapsulate the business logic, input validation, and outcome handling, providing a clean interface between the controller and the application's core functionality.
+
+### Outcomes
+
+Outcomes encapsulate the result of an interaction, providing a consistent interface for handling both success and failure scenarios. Outcomes can have an associated response, which can be set explicitly using the `with_response` method. The value of the outcome is separate from its response, allowing for more flexible handling of interaction results.
+<!-- ### Workflows
+
+Workflows allow you to compose multiple interactions into a larger, more complex business process while maintaining separation of concerns. -->
+## Core Components
+
+### Plutonium::Interaction::Base
+
+The foundation for all interactions. It integrates with ActiveModel for attribute definition and validations.
+
+```ruby
+class MyInteraction < Plutonium::Interaction::Base
+  attribute :some_input, :string
+  validates :some_input, presence: true
+
+  private
+
+  def execute
+    # Implementation
+  end
+end
+```
+
+### Plutonium::Interaction::Outcome
+
+Encapsulates the result of an interaction. It has two subclasses:
+
+- `Success`: Represents a successful operation
+- `Failure`: Represents a failed operation
+
+### Plutonium::Interaction::Response
+
+Represents controller operations that can be performed as a result of a successful interaction.
+We ship with these out of the box:
+
+- `Plutonium::Interaction::Response::Redirect`
+- `Plutonium::Interaction::Response::Render`
+- `Plutonium::Interaction::Response::Null`
+
+## Usage
+
+### Creating an Interaction
+
+1. Create a new file in `app/interactions/`, e.g., `app/interactions/users/create_user.rb`:
+
+   ```ruby
+   module Users
+     class CreateUser < Plutonium::Interaction::Base
+       attribute :first_name, :string
+       attribute :last_name, :string
+       attribute :email, :string
+
+       validates :first_name, :last_name, presence: true
+       validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+
+       private
+
+       def execute
+         user = User.new(attributes)
+         if user.save
+           success(user)
+             .with_response(Response::Redirect.new(user_path(user)))
+             .with_message("User was successfully created.")
+         else
+           failure(user.errors)
+         end
+       end
+     end
+   end
+   ```
+
+### Using an Interaction in a Controller
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    process_outcome(Users::CreateUser.call(user_params))
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:first_name, :last_name, :email)
+  end
+end
+```
+
+### Processing Outcomes
+
+In your `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  private
+
+  def process_outcome(outcome)
+    if outcome.success?
+      outcome.to_response.process(self) do |value|
+        # Default response.
+        # Executed if the interaction does not produce a specific Response.
+        render json: value
+      end
+    else
+      outcome.messages.each { |msg, type| flash.now[type] = msg }
+      render json: { errors: outcome.errors }, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+### Executing an Interaction
+
+Interactions can be executed using the call class method:
+
+```ruby
+outcome = MyInteraction.call(some_input: "value")
+
+if outcome.success?
+  # Handle success case
+else
+  # Handle failure case
+end
+```
+
+Or within another interaction:
+
+```ruby
+def execute
+  MyInteraction.call(some_input: "value")
+    .and_then { |result| do_something_with(result) }
+    .with_response(Response::Redirect.new(some_path(final_result)))
+    .with_message("Operation completed successfully")
+end
+```
+
+## Best Practices
+
+1. Keep interactions focused on a single responsibility
+2. Use meaningful names for interactions that describe the action being performed
+3. Leverage the `and_then` method for clean and expressive operation chaining
+4. Prefer small, composable interactions over large, monolithic ones
+5. Use `with_response` to explicitly set the desired response type
+6. Keep the interaction's core logic separate from response handling
+
+## Testing
+
+Interactions are easy to test in isolation. Here's an example using RSpec:
+
+```ruby
+RSpec.describe Users::CreateUser do
+  let(:valid_attributes) { { first_name: "John", last_name: "Doe", email: "john@example.com" } }
+
+  it "creates a user successfully" do
+    outcome = described_class.call(valid_attributes)
+
+    expect(outcome).to be_success
+    expect(outcome.value).to be_a(User)
+    expect(outcome.to_response).to be_a(Response::Redirect)
+    expect(User.last.email).to eq("john@example.com")
+  end
+
+  it "fails with invalid attributes" do
+    outcome = described_class.call(first_name: "", last_name: "Doe", email: "invalid")
+
+    expect(outcome).to be_failure
+    expect(outcome.errors).to include("First name can't be blank")
+    expect(outcome.errors).to include("Email is invalid")
+  end
+end
+```
+
+## Advanced Features
+
+<!--
+### Workflows
+
+Workflows allow you to compose multiple interactions into a larger business process:
+
+```ruby
+module Orders
+  class PlaceOrder < Plutonium::Interaction::Base
+    presents label: "Place Order",
+             icon: "shopping-cart",
+             description: "Process a new order"
+
+    attribute :user_id, :integer
+    attribute :product_ids, :string
+    attribute :payment_method, :string
+
+    validates :user_id, :product_ids, :payment_method, presence: true
+
+    workflow do
+      step :validate_products, ValidateProducts
+      step :check_inventory, CheckInventory
+      step :process_payment, ProcessPayment, if: ->(ctx) { ctx[:total_price] > 0 }
+      step :create_order, CreateOrder
+      step :send_confirmation, SendOrderConfirmation
+    end
+
+    private
+
+    def execute
+      execute_workflow(attributes.to_h)
+        .map { |ctx| Response::Redirect.new(order_path(ctx[:order])) }
+        .with_message("Order placed successfully.")
+    end
+  end
+end
+```
+-->
+
+### Presentable Concern
+
+The `Presentable` concern allows you to add metadata to your interactions, which can be used for generating UI components or documentation:
+
+```ruby
+class MyInteraction < Plutonium::Interaction::Base
+  include Plutonium::Interaction::Concerns::Presentable
+
+  presents label: "My Interaction",
+           icon: "star",
+           description: "Does something awesome"
+
+  # ... rest of the interaction
+end
+```
+
+## Examples
+
+### Chaining Operations
+
+```ruby
+module Orders
+  class PlaceOrder < Plutonium::Interaction::Base
+    attribute :user_id, :integer
+    attribute :product_ids, :string
+
+    private
+
+    def execute
+      success(attributes)
+        .and_then { |attrs| find_user(attrs[:user_id]) }
+        .and_then { |user| find_products(user, attributes[:product_ids]) }
+        .and_then { |user, products| create_order(user, products) }
+        .with_response(Response::Redirect.new(order_path(order)))
+        .with_message("Order placed successfully.")
+    end
+
+    def find_user(user_id)
+      user = User.find_by(id: user_id)
+      user ? success(user) : failure(["User not found"])
+    end
+
+    def find_products(user, product_ids)
+      products = Product.where(id: product_ids.split(','))
+      products.empty? ? failure(["No valid products found"]) : success([user, products])
+    end
+
+    def create_order(user, products)
+      order = Order.create(user: user, products: products)
+      order.persisted? ? success(order) : failure(order.errors.full_messages)
+    end
+  end
+end
+```
+
+This example demonstrates how to chain multiple operations, handle potential failures at each step, and return an appropriate outcome with a specific response type. Note how the `with_response` and `with_message` methods are used to set the response and add a message to the outcome.
+
+By following these guidelines and examples, you can effectively implement and use the Interaction pattern in your Rails applications, leading to more maintainable and testable code.
+
+<!--
+
+This example demonstrates how to chain multiple operations, handle potential failures at each step, and return an appropriate outcome.
+
+By following these guidelines and examples, you can effectively implement and use the Use Case Driven Design pattern in your Rails applications, leading to more maintainable and testable code.
+
+
+### Example interaction with workflow
+
+```ruby
+module Orders
+  class PlaceOrder < Plutonium::Interaction::Base
+    presents label: "Place Order",
+             icon: "shopping-cart",
+             description: "Process a new order",
+             category: "Order Management"
+
+    attribute :user_id, :integer
+    attribute :product_ids, :string
+    attribute :payment_method, :string
+
+    validates :user_id, :product_ids, :payment_method, presence: true
+
+    workflow do
+      step :validate_products, use_case: ValidateProducts
+      step :check_inventory, use_case: CheckInventory
+      step :process_payment, use_case: ProcessPayment, if: ->(ctx) { ctx[:total_price] > 0 }
+      step :create_order, use_case: CreateOrder
+      step :send_confirmation, use_case: SendOrderConfirmation
+    end
+
+    private
+
+    def execute
+      execute_workflow(attributes.to_h)
+        .map { |ctx| Actions::RedirectAction.new(:order_path, id: ctx[:order].id) }
+        .with_message("Order placed successfully.")
+    end
+  end
+
+  class ValidateProducts < Plutonium::Interaction::Base
+    # Implementation...
+  end
+
+  class CheckInventory < Plutonium::Interaction::Base
+    # Implementation...
+  end
+
+  class ProcessPayment < Plutonium::Interaction::Base
+    # Implementation...
+  end
+
+  class CreateOrder < Plutonium::Interaction::Base
+    # Implementation...
+  end
+
+  class SendOrderConfirmation < Plutonium::Interaction::Base
+    # Implementation...
+  end
+end
+```
+-->