plutonium 0.15.4 → 0.15.6

data/docs/guide/what-is-plutonium.md

@@ -0,0 +1,211 @@
+# What is Plutonium?
+
+Plutonium is a Rapid Application Development (RAD) toolkit that extends Rails with powerful conventions, patterns, and tools to accelerate application development while maintaining flexibility and maintainability.
+
+It acts as a higher-level abstraction on top of Rails, providing ready-to-use solutions for common application needs while preserving Rails' elegance.
+
+## Core Architecture
+
+### Rails-Native Design
+
+Plutonium integrates seamlessly with Rails, extending its conventions rather than replacing them:
+
+```ruby
+# Plutonium controllers inherit from your ApplicationController
+class ResourceController < ApplicationController
+  include Plutonium::Resource::Controller
+end
+
+# Plutonium controllers are Rails controllers
+class ProductsController < ResourceController
+  # Enhanced with resource capabilities
+  def custom_action
+    # Regular Rails code works just fine
+    respond_to do |format|
+      format.html
+      format.json
+    end
+  end
+end
+```
+
+### Resource-Oriented Architecture
+
+Resources are the building blocks of Plutonium applications:
+
+```ruby
+class ProductDefinition < ResourceDefinition
+  # Declarative field definitions
+  field :name, as: :string
+  field :description, as: :markdown
+  field :price_cents, as: :money
+
+  # Resource-level search
+  search do |scope, query|
+    scope.where("name LIKE ?", "%#{query}%")
+  end
+
+  # Business actions
+  action :publish, interaction: PublishProduct
+  action :archive, interaction: ArchiveProduct
+end
+```
+
+### Modular by Design
+
+Plutonium's packaging system helps organize code into focused, reusable modules:
+
+```ruby
+# Generate different types of packages
+rails generate pu:pkg:portal admin
+rails generate pu:pkg:package inventory
+
+# Packages are isolated and focused
+module AdminPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+  end
+end
+
+AdminPortal::Engine.routes.draw do
+  register_resource ::Product
+end
+```
+
+### Progressive Enhancement
+
+Built on modern web technologies like Hotwire, delivering rich interactivity without sacrificing simplicity:
+
+```ruby
+class PublishProduct < ResourceInteraction
+  attribute :schedule_for, :datetime
+  attribute :notify_users, :boolean
+
+  def execute
+    resource.publish!(schedule_for:)
+    notify_users! if notify_users
+
+    success(resource)
+      .with_message("Product scheduled for publishing")
+      .with_render_response(NotificationComponent.new)
+  end
+end
+```
+
+## Use Cases
+
+### Business Applications
+
+::: details Enterprise Resource Planning (ERP)
+```ruby
+class InvoiceDefinition < ResourceDefinition
+  # Rich field handling
+  field :line_items, as: :nested, limit: 20
+  field :attachments, as: :document, multiple: true
+
+  # Business actions
+  action :submit_for_approval, interaction: SubmitForApproval
+  action :approve, interaction: ApproveInvoice
+  action :reject, interaction: RejectInvoice
+
+  # Workflow states
+  scope :draft
+  scope :pending_approval
+  scope :approved
+end
+```
+:::
+
+::: details Multi-tenant SaaS
+```ruby
+module CustomerPortal
+  class Engine < Rails::Engine
+    include Plutonium::Package::Engine
+    # Automatic tenant isolation
+    scope_to_entity Organization
+  end
+end
+```
+:::
+
+### Administrative Systems
+
+::: details Back-office Applications
+```ruby
+class OrderDefinition < ResourceDefinition
+  # Advanced filtering
+  filter :status, with: SelectFilter, choices: Order.statuses
+  filter :created_at, with: DateRangeFilter
+
+  # Bulk actions
+  action :process_batch, interaction: ProcessPendingOrders
+  action :export_to_csv, interaction: ExportOrders
+
+  # Complex displays
+  display :summary do |field|
+    OrderSummaryComponent.new(field)
+  end
+end
+```
+:::
+
+::: details Content Management
+```ruby
+class ArticleDefinition < ResourceDefinition
+  field :content, as: :markdown
+  field :featured_image, as: :image
+
+  # Publishing workflow
+  action :publish, interaction: PublishArticle
+  action :schedule, interaction: ScheduleArticle
+
+  # Content organization
+  scope :draft
+  scope :published
+  scope :scheduled
+end
+```
+:::
+
+## Key Benefits
+
+### Accelerated Development
+- Pre-built components for common functionality
+- Smart generators for boilerplate code
+- Convention-based resource handling
+- Integrated authentication and authorization
+
+### Maintainable Architecture
+- Clear separation of concerns through packages
+- Consistent patterns across the application
+- Deep Rails integration
+- Progressive enhancement
+
+### Enterprise Ready
+- Flexible and robust access control
+- Multi-tenancy support
+- Extensible component system
+- Mobile-friendly by default
+
+## Best For
+
+::: tip IDEAL USE CASES
+- Complex business applications
+- Multi-tenant SaaS platforms
+- Administrative systems
+- Content management systems
+- Resource management systems
+:::
+
+::: warning MIGHT NOT BE THE BEST FIT
+- Simple blogs or brochure sites
+- Basic CRUD applications
+- Pure API-only services
+:::
+
+## Prerequisites
+
+- Ruby 3.2.2 or higher
+- Rails 7.1 or higher
+- Node.js and Yarn
+- Basic understanding of Ruby on Rails

data/docs/index.md

@@ -0,0 +1,43 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: Plutonium RADKit
+  tagline: The Ultimate Rapid Application Development Toolkit (RADKit) for Rails
+  image:
+    src: /plutonium.png
+    alt: Plutonium
+  actions:
+    - theme: brand
+      text: Get started
+      link: /guide/getting-started/
+    - theme: alt
+      text: Learn more
+      link: /guide/what-is-plutonium
+
+features:
+  - title: Pro-Grade CRUD UI
+    details: Stunning, modern interface with rich field types to build powerful admin panels in minutes
+
+  - title: Intelligent Fields
+    details: Zero-config field detection that matches your Rails models out of the box
+
+  - title: Seamless Authentication
+    details: Use your existing auth or our Rodauth integration - get setup in seconds
+
+  - title: Enterprise Authorization
+    details: Industrial-strength access control powered by Action Policy's proven framework
+
+  - title: Built-in Multitenancy
+    details: Row-level multitenancy that just works - perfect for SaaS and enterprise apps
+
+  - title: Advanced Nested Resources
+    details: Complex resource relationships made simple with zero extra configuration
+
+  - title: Custom Actions
+    details: Extend your admin panel with incredibly simple custom actions and workflows
+
+  - title: Complete Builder Control
+    details: Total flexibility to customize every aspect of your admin UI with elegant builder APIs
+---

data/docs/markdown-examples.md

@@ -0,0 +1,85 @@
+# Markdown Extension Examples
+
+This page demonstrates some of the built-in markdown extensions provided by VitePress.
+
+## Syntax Highlighting
+
+VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
+
+**Input**
+
+````md
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**Output**
+
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+## Custom Containers
+
+**Input**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**Output**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+## More
+
+Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).

data/docs/public/site.webmanifest

@@ -0,0 +1 @@
+{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}

data/docs/public/templates/plutonium.rb

@@ -0,0 +1,21 @@
+after_bundle do
+  # We just installed Rails, let's create a commit
+  git add: "."
+  git commit: %( -m 'initial commit' )
+
+  # Run the base install
+  rails_command "app:template LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb"
+
+  # Add development tools
+  generate "pu:gem:dotenv"
+  git add: "."
+  git commit: %( -m 'add dotenv' )
+
+  generate "pu:gem:annotate"
+  git add: "."
+  git commit: %( -m 'add annotate' )
+
+  generate "pu:core:assets"
+  git add: "."
+  git commit: %( -m 'integrate assets' )
+end

data/lib/generators/pu/core/assets/assets_generator.rb

@@ -22,12 +22,11 @@ module Pu
       private
 
       def copy_tailwind_config
-        copy_file "tailwind.config.js"
+        copy_file "tailwind.config.js", force: true
       end
 
       def install_dependencies
-        `yarn add @radioactive-labs/plutonium`
-        `yarn add flowbite @tailwindcss/forms`
+        run "npm install @radioactive-labs/plutonium flowbite @tailwindcss/forms"
       end
 
       def configure_application

data/lib/generators/pu/core/assets/templates/tailwind.config.js

@@ -9,12 +9,12 @@ module.exports = {
   ].concat(plutoniumTailwindConfig.plugins.map((plugin) => require(plugin))),
   theme: plutoniumTailwindConfig.theme,
   content: [
+    `${__dirname}/app/**/*.rb`,
     `${__dirname}/app/views/**/*.html.erb`,
     `${__dirname}/app/helpers/**/*.rb`,
     `${__dirname}/app/assets/stylesheets/**/*.css`,
     `${__dirname}/app/javascript/**/*.js`,
-    `${__dirname}/app/plutonium/**/*.rb`,
-    `${__dirname}/packages/**/app/plutonium/**/*.rb`,
+    `${__dirname}/packages/**/app/**/*.rb`,
     `${__dirname}/packages/**/app/views/**/*.html.erb`,
   ].concat(plutoniumTailwindConfig.content),
 }

data/lib/generators/pu/core/install/install_generator.rb

@@ -15,6 +15,7 @@ module Pu
         setup_packages
         setup_app
         eject_views
+        setup_active_record
       rescue => e
         exception "#{self.class} failed:", e
       end
@@ -25,7 +26,6 @@ module Pu
         copy_file "config/packages.rb"
         create_file "packages/.keep"
         insert_into_file "config/application.rb", "\nrequire_relative \"packages\"\n", after: /Bundler\.require.*\n/
-        # insert_into_file "config/application.rb", indent("Plutonium.configure_rails config\n\n", 4), after: /.*< Rails::Application\n/
       end
 
       def setup_app
@@ -38,6 +38,14 @@ module Pu
           force: options[:force],
           skip: options[:skip]
       end
+
+      def setup_active_record
+        inject_into_class(
+          "app/models/application_record.rb",
+          "ApplicationRecord",
+          "  include Plutonium::Resource::Record\n"
+        )
+      end
     end
   end
 end

data/lib/generators/pu/core/install/templates/config/initializers/plutonium.rb

@@ -3,6 +3,5 @@
 Plutonium.configure do |config|
   config.load_defaults 1.0
 
-  # config.assets.logo = "logo.png"
   # Configure plutonium above.
 end

data/lib/plutonium/core/controllers/authorizable.rb

@@ -9,7 +9,7 @@ module Plutonium
 
         included do
           authorize :user, through: :current_user
-          authorize :scope, through: :entity_scope_for_authorize
+          authorize :entity_scope, through: :entity_scope_for_authorize
 
           helper_method :policy_for, :authorized_resource_scope
         end

data/lib/plutonium/definition/base.rb

@@ -46,6 +46,10 @@ module Plutonium
 
       class Display < Plutonium::UI::Display::Resource; end
 
+      class QueryForm < Plutonium::UI::Form::Query; end
+
+      class TextFilter < Plutonium::Query::Filters::Text; end
+
       # fields
       defineable_props :field, :input, :display, :column
 
@@ -94,6 +98,10 @@ module Plutonium
       def detail_class
         self.class::Display
       end
+
+      def query_form
+        self.class::QueryForm
+      end
     end
   end
 end

data/lib/plutonium/definition/defineable_props.rb

@@ -67,7 +67,7 @@ module Plutonium
                   end
                   # merged[name].compact!
                 end
-                merged
+                Plutonium::Lib::DeepFreezer.freeze(merged)
               end
             end
 

data/lib/plutonium/definition/presentable.rb

@@ -0,0 +1,71 @@
+module Plutonium
+  module Definition
+    # Provides presentation-related functionality for interactions.
+    #
+    # This module allows interactions to define metadata such as labels, icons,
+    # and descriptions, which can be used for UI generation or documentation.
+    #
+    # @example
+    #   class MyInteraction < Plutonium::Interaction::Base
+    #     include Plutonium::Definition::Presentable
+    #
+    #     presents label: "My Interaction",
+    #              icon: "star",
+    #              description: "Does something awesome"
+    #
+    #     # ... rest of the interaction
+    #   end
+    module Presentable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :presentation_metadata, default: {}
+      end
+
+      class_methods do
+        # Defines presentation metadata for the interaction.
+        #
+        # @param options [Hash] The presentation options.
+        # @option options [String] :label The label for the interaction.
+        # @option options [String] :icon The icon for the interaction.
+        # @option options [String] :description The description of the interaction.
+        def presents(**options)
+          self.presentation_metadata = options
+        end
+
+        # Returns the label for the interaction.
+        #
+        # @return [String] The label defined in the presentation metadata or a default generated from the class name.
+        def label
+          presentation_metadata[:label] || name.demodulize.titleize
+        end
+
+        # Returns the icon for the interaction.
+        #
+        # @return [String, nil] The icon defined in the presentation metadata.
+        def icon
+          presentation_metadata[:icon]
+        end
+
+        # Returns the description for the interaction.
+        #
+        # @return [String, nil] The description defined in the presentation metadata.
+        def description
+          presentation_metadata[:description]
+        end
+      end
+
+      def label
+        self.class.label
+      end
+
+      def icon
+        self.class.icon
+      end
+
+      def description
+        self.class.description
+      end
+    end
+  end
+end

data/lib/plutonium/interaction/README.md

@@ -252,7 +252,7 @@ The `Presentable` concern allows you to add metadata to your interactions, which
 
 ```ruby
 class MyInteraction < Plutonium::Interaction::Base
-  include Plutonium::Interaction::Concerns::Presentable
+  include Plutonium::Definition::Presentable
 
   presents label: "My Interaction",
            icon: Phlex::TablerIcons::Activate,

data/lib/plutonium/interaction/base.rb

@@ -22,10 +22,10 @@ module Plutonium
     class Base
       include ActiveModel::Model
       include ActiveModel::Attributes
-      include Concerns::Presentable
       include Plutonium::Definition::DefineableProps
       include Plutonium::Definition::ConfigAttr
-      # include Concerns::WorkflowDSL
+      include Plutonium::Definition::Presentable
+      # include Plutonium::Interaction::Concerns::WorkflowDSL
 
       class Form < Plutonium::UI::Form::Interaction; end
 
@@ -44,6 +44,10 @@ module Plutonium
         self::Form.new(instance || new)
       end
 
+      def build_form
+        self.class.build_form(self)
+      end
+
       # Executes the interaction.
       #
       # @return [Plutonium::Interaction::Outcome] The result of the interaction.
@@ -60,10 +64,6 @@ module Plutonium
         end
       end
 
-      def build_form
-        self.class.build_form(self)
-      end
-
       private
 
       # Implement the main logic of the interaction.

data/lib/plutonium/lib/deep_freezer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Lib
+    class DeepFreezer
+      def self.freeze(object)
+        #  Recursive calling #deep_freeze for enumerable objects.
+        if object.respond_to? :each
+          if object.instance_of?(Hash)
+            object.each { |key, val| freeze(val) }
+          else
+            object.each { |val| freeze(val) }
+          end
+        end
+
+        # #  Freezing of all instance variable values.
+        # object.instance_variables.each do |var|
+        #   frozen_val = instance_variable_get(var)
+        #   frozen_val.deep_freeze
+        #   instance_variable_set(var, frozen_val)
+        # end
+
+        if object.frozen?
+          object
+        else
+          object.freeze
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/query/adhoc_block.rb

@@ -0,0 +1,19 @@
+module Plutonium
+  module Query
+    class AdhocBlock < Base
+      attr_reader :body
+
+      # Initializes a AdhocBlock with a given block of code.
+      #
+      # @param body [Proc] The block of code for the query.
+      def initialize(body)
+        super()
+        @body = body
+      end
+
+      def apply(scope, **)
+        body.call(scope, **)
+      end
+    end
+  end
+end

data/lib/plutonium/query/base.rb

@@ -0,0 +1,29 @@
+module Plutonium
+  module Query
+    class Base
+      include Plutonium::Definition::DefineableProps
+      include Plutonium::Definition::ConfigAttr
+      include Plutonium::Definition::Presentable
+
+      defineable_props :field, :input
+
+      # Applies a parameterized query to modify the given scope.
+      #
+      # @param scope [Object] The initial scope that will be filtered, sorted, or otherwise modified
+      #   by applying this query. This is typically an ActiveRecord::Relation or similar query object.
+      #
+      # @param params [Hash] Optional parameters that configure how the query is applied.
+      #   The specific parameters accepted depend on the implementing class.
+      #
+      # @return [Object] The modified scope with this query's conditions applied. Returns the same
+      #   type as the input scope parameter.
+      #
+      # @example Basic usage
+      #   query.apply(User.all, status: 'active')
+      #
+      def apply(scope, **params)
+        raise NotImplementedError, "#{self.class}#apply(scope, **params)"
+      end
+    end
+  end
+end