plutonium 0.15.5 → 0.15.6

data/docs/guide/getting-started/resources.md

@@ -0,0 +1,254 @@
+# Working with Resources
+
+::: tip What you'll learn
+- How to create and manage resources in Plutonium
+- Understanding resource definitions and configurations
+- Working with fields, associations, and nested resources
+- Implementing resource policies and scoping
+- Best practices for resource organization
+:::
+
+## Introduction
+
+Resources are the core building blocks of a Plutonium application. A resource represents a model in your application that can be managed through a consistent interface, complete with views, controllers, and policies.
+
+## Creating a Resource
+
+The fastest way to create a resource is using the scaffold generator:
+
+```bash
+rails generate pu:res:scaffold Blog user:belongs_to title:string content:text state:string published_at:datetime?
+```
+
+This generates several files, including:
+
+::: code-group
+```ruby [app/models/blog.rb]
+class Blog < ResourceRecord
+  belongs_to :user
+end
+```
+
+```ruby [app/policies/blog_policy.rb]
+class BlogPolicy < Plutonium::Resource::Policy
+  def create?
+    true
+  end
+
+  def read?
+    true
+  end
+
+  def permitted_attributes_for_create
+    %i[user title content state published_at]
+  end
+
+  def permitted_attributes_for_read
+    %i[user title content state published_at]
+  end
+end
+```
+
+```ruby [app/definitions/blog_definition.rb]
+class BlogDefinition < Plutonium::Resource::Definition
+end
+```
+:::
+
+## Resource Definitions
+
+Resource definitions customize how a resource behaves in your application. They define:
+- Fields and their types
+- Available actions
+- Search and filtering capabilities
+- Sorting options
+- Display configurations
+
+### Basic Field Configuration
+
+::: code-group
+```ruby [Simple Fields]
+class BlogDefinition < Plutonium::Resource::Definition
+  # Basic field definitions
+  field :content, as: :text
+
+  # Field with custom display options
+  field :published_at,
+        as: :datetime,
+        hint: "When this post should be published"
+end
+```
+
+```ruby [Custom Displays]
+class BlogDefinition < Plutonium::Resource::Definition
+  # Customize how fields are displayed
+  display :title, class: "col-span-full"
+  display :content do |f|
+    f.text_tag class: "prose dark:prose-invert"
+  end
+
+  # Custom column display in tables
+  column :state, align: :right
+end
+```
+:::
+
+<!--
+### Working with Associations
+
+Plutonium makes it easy to work with Rails associations:
+
+```ruby
+class BlogDefinition < Plutonium::Resource::Definition
+  # Define belongs_to association
+  field :user, as: :belongs_to
+
+  # Has-many association with inline creation
+  field :comments do |f|
+    f.has_many_tag nested: true
+  end
+
+  # Configure nested attributes
+  define_nested_input :comments,
+    inputs: %i[content user],
+    limit: 3 do |input|
+      input.define_field_input :content,
+        type: :text,
+        hint: "Keep it constructive"
+    end
+end
+```
+-->
+
+### Adding Custom Actions
+
+Beyond CRUD, you can add custom actions to your resources:
+
+```ruby
+# app/interactions/blogs/publish.rb
+module Blogs
+  class Publish < Plutonium::Resource::Interaction
+    # Define what this interaction accepts
+    attribute :resource, class: Blog
+    attribute :publish_date, :date, default: -> { Time.current }
+
+    presents label: "Publish Blog",
+             icon: Phlex::TablerIcons::Send,
+             description: "Make this blog post public"
+
+    private
+
+    def execute
+      if resource.update(
+        state: "published",
+        published_at: publish_date
+      )
+        succeed(resource)
+          .with_message("Blog post published successfully")
+          .with_redirect_response(resource)
+      else
+        failed(resource.errors)
+      end
+    end
+  end
+end
+
+# app/definitions/blog_definition.rb
+class BlogDefinition < Plutonium::Resource::Definition
+  # Register the custom action
+  action :publish,
+    interaction: Blogs::Publish,
+    category: :primary
+end
+```
+
+### Search and Filtering
+
+Add search and filtering capabilities to your resources:
+
+```ruby
+class BlogDefinition < Plutonium::Resource::Definition
+  # Enable full-text search
+  search do |scope, query|
+    scope.where("title ILIKE ? OR content ILIKE ?",
+      "%#{query}%", "%#{query}%")
+  end
+
+  # Add filters
+  filter :state,
+    with: SelectFilter,
+    choices: %w[draft published]
+
+  filter :published_at,
+    with: DateFilter,
+    predicate: :gteq
+
+  # Add scopes
+  scope :published do |scope|
+    where(state: "published")
+  end
+  scope :draft do |scope|
+    where(state: "draft")
+  end
+
+  # Configure sorting
+  sort :title
+  sort :published_at
+end
+```
+
+## Resource Policies
+
+Policies control access to your resources:
+
+```ruby
+class BlogPolicy < Plutonium::Resource::Policy
+  def permitted_attributes_for_create
+    %i[title content state published_at user_id]
+  end
+
+  def permitted_associations
+    %i[comments]
+  end
+
+  def create?
+    # Allow logged in users to create blogs
+    user.present?
+  end
+
+  def update?
+    # Users can only edit their own blogs
+    record.user_id == user.id
+  end
+
+  def publish?
+    # Only editors can publish
+    user.editor? && record.draft?
+  end
+
+  # Scope visible records
+  relation_scope do |relation|
+    relation = super(relation)
+    next relation unless user.admin?
+
+    relation.with_deleted
+  end
+end
+```
+
+## Best Practices
+
+::: tip Resource Organization
+1. Keep resource definitions focused and cohesive
+2. Use packages to organize related resources
+3. Leverage policy scopes for authorization
+4. Extract complex logic into interactions
+5. Use presenters for view-specific logic
+:::
+
+::: warning Common Pitfalls
+- Avoid putting business logic in definitions
+- Don't bypass policy checks
+- Remember to scope resources appropriately
+- Test your interactions and policies
+:::

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