plutonium 0.15.8 → 0.15.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66eaba0172a0f59aac7d9d3eb9f062b3d68b6a3bd393fb461acb903e8a94c517
-  data.tar.gz: bed5cac13ba7baaca2898ea4a5ffcedaf82ec1fc40371a8d96fa3ab30870cd5b
+  metadata.gz: 3b2141de8e221952e48ec05c98fdd3daf1491f5acbf52ea7426a200426a2cdb5
+  data.tar.gz: c42d5d1c89bff5c1141b2dc053e552d03800be87515354b3793b261c0321b068
 SHA512:
-  metadata.gz: a6be6c9fc4b04a0949b387afb27c6dfed6853742d7c44828dc059c08a4d4524be148652c44b92a63468ccb2fb82eb1a1d49564d9e2e6580a8942f9c2592c9fc0
-  data.tar.gz: 7226710b58afbe68b6a21cc8b2fa8b2ff4aec519aefd047c1d7c9114e4860cb0127d2584722a9f2979af62bd4f0cdeeceafbb7e813f90365c829dfd76c7ad79a
+  metadata.gz: 4738b043d687cfe05a908749b9db742d7334d874add0ff51c26da8fc2dcf675aebe8333fe2a58d47dcda312e52c4a463a61d6a3f2fdf64b2a26b3a5a7da21d8f
+  data.tar.gz: 43b7d66a30196c427f93c595568ae51ce6d2f8cad581d12f0e0d5a83398f68bf372c82d0346bc3cca9c4fce0020f9db3d180e77afff129c14055b17ab2900713

data/README.md

@@ -1,95 +1,33 @@
-# Plutonium: Nuclear ☢️ Reactor Included
+# Plutonium: It's like Rails, but for Rails!
 
 [![Ruby](https://github.com/radioactive-labs/plutonium-core/actions/workflows/main.yml/badge.svg)](https://github.com/radioactive-labs/plutonium-core/actions/workflows/main.yml)
 
-Watch the introduction video: [Plutonium in 30 minutes](https://www.youtube.com/watch?v=HMjzj-vVLIU)
+**Plutonium** is a powerful Rapid Application Development (RAD) toolkit for Rails that picks up where Rails left off, introducing application-level concepts and tooling that transform the way you build applications.
 
----
+## Overview
 
-**Plutonium** picks up where Rails left off, introducing application level concepts and tooling, transforming the way you build applications with Rails.
-It's a culmination of lessons learned from years of developing nearly identical applications and is designed to save you from the drudgery of re-implementation.
+Plutonium builds upon Rails' conventions and extends them with:
 
-**Why Choose Plutonium?**
+- **Authentication & Authorization**: Integrates seamlessly with Rodauth or your existing auth system
+- **Complete CRUD Operations**: Rich fields, forms, tables, and nested resources out of the box
+- **Modular Architecture**: Package system based on Rails engines for better organization
+- **Entity Scoping**: Built-in multi-tenancy support that "just works"
+- **Smart Generators**: Eliminate boilerplate while maintaining flexibility
+- **Modern UI**: Beautiful, responsive interface powered by Tailwind CSS and Hotwire
 
-- **Efficiency by Design:** Plutonium is built for developers who demand efficiency without compromise. It automates 90% of your application needs while giving you the flexibility to tailor the remaining 10% to your specific requirements.
-- **Comprehensive Features:** Plutonium covers a wide array of functionalities out of the box:
-  - Authentication & Authorization
-  - Complete CRUD operations with advanced features: customizable inputs, fields, tables, forms, pagination, actions, search, scopes, filtering, nested resources and much more.
-  - Modular architecture leveraging Rails engines for improved packaging and namespacing.
-  - Time-saving generators for boilerplate tasks.
-- **Omakase with a Twist:** Inspired by Rails' omakase philosophy, Plutonium delivers a convention-based approach but doesn't box you in. It's seamlessly integrated into your project, allowing you to write your application as you would with vanilla Rails but with powerful extensions.
-- **MVC and Beyond:** Plutonium adopts the MVC pattern, enhanced with modern web technologies like [hotwire](TODO), to deliver an interactive and robust user experience. It emphasizes progressive enhancement, ensuring a smooth development process and end-user experience.
-- **Rails Harmony:** A Plutonium app is a Rails app at its core. It respects and builds upon Rails' conventions, making it intuitive for Rails developers. If you know Rails, learning Plutonium requires only a few new concepts.
-- **Effortless Customization:** Plutonium is designed for easy customization to meet your unique requirements. Whether adjusting the functionality of entire resource groups or fine-tuning individual elements, our accessible low-level APIs and the familiar Rails conventions offer unparalleled flexibility. This ensures that any modifications you need to make can be implemented swiftly and smoothly, reducing complexity and enhancing your development experience.
-- **Community-Driven Dependencies:** Plutonium stands on the shoulders of giants, integrating with well-established gems chosen for their robustness and flexibility, including:
-  - [ActiveInteraction](https://github.com/AaronLasseigne/active_interaction) for business logic
-  - [Pagy](https://github.com/ddnexus/pagy) for pagination
-  - [Action Policy](https://actionpolicy.evilmartians.io/): for authorization
-  - [Simple Form](https://github.com/heartcombo/simple_form) for forms
-  - [Rodauth](https://github.com/jeremyevans/rodauth) (via [rodauth-rails](https://github.com/janko/rodauth-rails)) for authentication. Rodauth is optional, allowing flexibility in choosing your auth solution
+## Project Status
 
-## Quick Start
+> [!WARNING]
+> While Plutonium is actively used in production environments, it's still in early development. APIs may change, and some features are still evolving. We recommend thoroughly testing before deploying to production.
 
-Get Plutonium up and running in your Rails application with these simple steps:
+## Documentation
 
-1. **Add Plutonium to your Gemfile:**
-
-```ruby
-gem "plutonium"
-```
-
-2. **Bundle Install:**
-
-```shell
-bundle
-```
-
-3. **Install Plutonium:**
-
-```shell
-rails g pu:core:install
-```
-
-Start building your Rails applications faster, with more flexibility and less boilerplate. **Plutonium** is here to revolutionize your development process.
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To build assets, run `npm dev`
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/plutonium.
+Visit our [documentation](https://radioactive-labs.github.io/plutonium-core/) for:
+- Getting started guide
+- Installation instructions
+- Core concepts
+- Tutorials
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-<!--
-# ------------------------------
-
-gem "plutonium", path: "/Users/stefan/code/plutonium/starters/plutonium/"
-gem "plutonium_generators", github: "radioactive-labs/plutonium-generators", group: [:development, :test]
-
-
-
-# rails new vulcan \
-#                --skip-action-mailbox --skip-action-text --skip-active-storage --skip-action-cable --skip-jbuilder \
-#                --skip-test --skip-system-test --javascript=esbuild --css=bootstrap --database=postgresql
-
-
-```bash
-rails new pluton8_starter --name="Pluton8 Starter" --database=sqlite3 --skip-action-mailbox --skip-action-text --skip-active-storage --asset-pipeline=propshaft --skip-jbuilder --javascript=importmap --css=tailwind
-
-bin/rails app:template LOCATION=/Users/stefan/code/plutonium/starters/vulcan/gems/plutonium/templates/base.rb
-```
-
-rails g pu:rodauth:account admin --no-defaults --login --logout --remember --change-password --internal-request --create-account --lockout --verify-account --audit-logging --close-account --otp --reset-password --reset-password-notify --active-sessions --recovery-codes --password-grace-period
--->

data/docs/.vitepress/config.ts

@@ -26,6 +26,7 @@ export default defineConfig(withMermaid({
           text: "Introduction",
           items: [
             { text: "What is Plutonium?", link: "/guide/what-is-plutonium" },
+            { text: "Tutorial", link: "/guide/tutorial" },
           ]
         },
         {

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

@@ -1,7 +1,6 @@
 # Getting Started with Plutonium
 
 <!--
-This guide covers getting up and running with Plutonium.
 
 After reading this guide, you will know:
 
@@ -10,6 +9,10 @@ After reading this guide, you will know:
 - The basic principles of Resource design.
 - How to quickly generate the starting pieces of a Plutonium application.
 -->
+This guide covers getting up and running with Plutonium.
+It is intended to be a more detailed guide.
+
+If you're interested in a quick start, check out our [tutorial](/guide/tutorial).
 
 ## Prerequisites
 

data/docs/guide/tutorial.md

@@ -0,0 +1,403 @@
+# Building a Blog with Plutonium
+
+# Building a Blog with Plutonium
+
+> **Quick Links:**
+> - 🔍 [Tutorial Demo](https://github.com/radioactive-labs/plutonium-app)
+> - 📂 [Tutorial Source Code](https://github.com/radioactive-labs/plutonium-app)
+
+This tutorial walks through building a blog application using Plutonium. You'll learn how to:
+
+- Set up authentication using Rodauth
+- Create a blog feature package
+- Build a dashboard/portal
+- Implement posts and comments
+- Add interactive actions
+- Configure scoping and authorization
+
+[Rest of the tutorial content remains exactly the same...]
+
+## Initial Setup
+
+Let's start by creating a new Rails application with Plutonium:
+
+```bash
+rails new plutonium_app -a propshaft -j esbuild -c tailwind \
+  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+```
+
+This creates a new Rails application with:
+- Propshaft as the asset pipeline
+- esbuild for JavaScript bundling
+- Tailwind CSS for styling
+- Plutonium's base configuration
+
+## Setting Up Authentication
+
+Next, let's add authentication using Rodauth:
+
+```bash
+# Generate Rodauth configuration
+rails generate pu:rodauth:install
+
+# Generate user account setup
+rails generate pu:rodauth:account user
+rails db:migrate
+```
+
+This sets up:
+- A User model with authentication
+- Login/logout functionality
+- Account verification via email
+- Password reset capabilities
+
+![Plutonium Login Page](/tutorial/plutonium-login-page.png)
+
+The key files created include:
+- `app/models/user.rb` - The User model
+- `app/rodauth/user_rodauth_plugin.rb` - Rodauth configuration
+- `app/controllers/rodauth_controller.rb` - Base controller for auth pages
+- Database migrations for users and auth-related tables
+
+## Creating the Blog Feature Package
+
+Let's create a dedicated package for our blogging functionality:
+
+```bash
+rails generate pu:pkg:package blogging
+```
+
+This generates a new feature package under `packages/blogging/` with:
+- Base controllers
+- Model and policy base classes
+- Package-specific views directory
+- Engine configuration
+
+## Adding Posts Resource
+
+Now we can add our first resource - blog posts:
+
+```bash
+rails generate pu:res:scaffold post user:belongs_to title:string \
+  content:text 'published_at:datetime?'
+```
+
+::: tip
+Unlike Rails, Plutonium generates fields as non-null by default.
+Appending `?` to the type e.g. `published_at:datetime?` makes `published_at` a **nullable** datetime.
+:::
+
+When prompted, select the `blogging` feature package.
+
+This creates:
+- Post model with associations
+- Policy class with basic permissions
+- Controllers for CRUD operations
+- Database migration
+
+The generated post model includes:
+```ruby
+class Blogging::Post < Blogging::ResourceRecord
+  belongs_to :user
+  validates :title, presence: true
+  validates :content, presence: true
+end
+```
+
+Remember to apply the new migrations:
+```bash
+rails db:migrate
+```
+
+## Creating the Dashboard Portal
+
+Let's add a portal to manage our blog:
+
+```bash
+rails generate pu:pkg:portal dashboard
+```
+
+When prompted, select `user` for authentication.
+
+This creates a new portal package under `packages/dashboard_portal/` with:
+- Portal-specific controllers
+- Resource presentation layer
+- Dashboard views
+- Authenticated routes
+
+## Configure Routes
+
+Let's configure our application routes to properly handle authentication and dashboard access:
+
+::: code-group
+```ruby [app/rodauth/user_rodauth_plugin.rb]
+# ==> Redirects
+
+# Redirect to home after login.
+create_account_redirect "/" # [!code --]
+create_account_redirect "/dashboard" # [!code ++]
+
+# Redirect to home after login.
+login_redirect "/" # [!code --]
+login_redirect "/dashboard" # [!code ++]
+
+# Redirect to home page after logout.
+logout_redirect "/" # [!code --]
+logout_redirect "/dashboard" # [!code ++]
+
+# Redirect to wherever login redirects to after account verification.
+verify_account_redirect { login_redirect }
+```
+
+```ruby [config/routes.rb]
+Rails.application.routes.draw do
+  # Other routes...
+
+  # Defines the root path route ("/")
+  # root "posts#index" # [!code --]
+  root to: redirect("/dashboard") # [!code ++]
+end
+```
+:::
+
+These changes ensure that:
+- Users are directed to the dashboard after signing up
+- Users are directed to the dashboard after logging in
+- Users are directed to the dashboard after logging out
+- The root URL (`/`) redirects to the dashboard
+- Account verification follows the same flow as login
+
+## Connecting Posts to Dashboard
+
+We can now connect our blog posts to the dashboard:
+
+```bash
+rails generate pu:res:conn
+```
+
+Select:
+1. Source feature: `blogging`
+2. Resources: `Blogging::Post`
+3. Portal: `dashboard_portal`
+
+This configures the routing and controllers to display posts in the dashboard.
+
+![Plutonium Posts Dashboard](/tutorial/plutonium-posts-dashboard.png)
+
+## Adding Comments
+
+Let's add commenting functionality:
+
+```bash
+rails generate pu:res:scaffold comment blogging/post:belongs_to \
+  user:belongs_to body:text
+
+rails db:migrate
+
+rails generate pu:res:conn
+```
+
+::: tip
+Note the use of the namespaced model in the association `blogging/post`.
+
+Plutonium has inbuilt support for handling namespaces, generating:
+```ruby
+# model
+belongs_to :post, class_name: "Blogging::Post"
+
+# migration
+t.belongs_to :post, null: false, foreign_key: {:to_table=>:blogging_posts}
+```
+:::
+
+This creates:
+- Comment model with associations
+- Policy controlling access
+- CRUD interface in dashboard
+- Proper routing configuration
+
+## Customizing the Interface
+
+### Post Table Customization
+
+We can customize how posts appear in the table view:
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+def permitted_attributes_for_index
+  [:user, :title, :published_at, :created_at]
+end
+```
+
+![Plutonium Posts Dashboard (Customized)](/tutorial/plutonium-posts-dashboard-customized.png)
+
+### Post Detail View
+
+Customize the post detail layout using display grids:
+
+```ruby
+# packages/blogging/app/definitions/blogging/post_definition.rb
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  display :user, class: "col-span-full"
+  display :title, class: "col-span-full"
+  display :content, class: "col-span-full"
+  display :published_at, class: "col-span-full"
+end
+```
+
+![Plutonium Posts Detail (Customized)](/tutorial/plutonium-posts-detail-customized.png)
+
+## Adding Publishing Functionality
+
+Let's add the ability to publish posts:
+
+::: code-group
+
+```ruby [post_definition.rb]
+# packages/blogging/app/definitions/blogging/post_definition.rb
+action :publish,
+       interaction: Blogging::Posts::Publish,
+       collection_record_action: false # do not show this on the table
+```
+
+```ruby [publish.rb]
+# packages/blogging/app/interactions/blogging/posts/publish.rb
+module Blogging
+  module Posts
+    class Publish < ResourceInteraction
+      presents label: "Publish Post", icon: Phlex::TablerIcons::Send
+      attribute :resource
+
+      def execute
+        if resource.update(published_at: Time.current)
+          succeed(resource)
+            .with_message("Post was successfully published")
+        else
+          failed(resource.errors)
+        end
+      end
+    end
+  end
+end
+```
+
+```ruby [post_policy.rb]
+# packages/blogging/app/policies/blogging/post_policy.rb
+
+def publish? # [!code ++]
+  !record.published_at # [!code ++]
+end # [!code ++]
+
+
+def permitted_attributes_for_create
+  [:user, :title, :content, :published_at] # [!code --]
+  [:user, :title, :content] # [!code ++]
+end
+```
+
+:::
+
+![Plutonium Publish Post](/tutorial/plutonium-publish-post.png)
+
+## Adding Comments Panel
+
+Enable viewing comments on posts:
+
+::: code-group
+
+```ruby [post.rb]
+# packages/blogging/app/models/blogging/post.rb
+has_many :comments
+```
+
+```ruby [post_policy.rb]
+# packages/blogging/app/policies/blogging/post_policy.rb
+def permitted_associations
+  %i[comments]
+end
+```
+
+:::
+
+![Plutonium Comments Panel](/tutorial/plutonium-association-panel.png)
+
+## Scoping Resources
+
+Ensure users only see their own content:
+
+```ruby
+# packages/dashboard_portal/lib/engine.rb
+module DashboardPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      scope_to_entity User, strategy: :current_user
+    end
+  end
+end
+```
+
+## Adding Nested Comments
+
+Enable adding comments directly from the post form:
+
+::: code-group
+
+```ruby [post_definition.rb]
+# packages/blogging/app/definitions/blogging/post_definition.rb
+nested_input :comments,
+  using: Blogging::CommentDefinition,
+  fields: %i[user body]
+```
+
+```ruby [post.rb]
+# packages/blogging/app/models/blogging/post.rb
+has_many :comments
+accepts_nested_attributes_for :comments # [!code ++]
+```
+
+```ruby [post_policy.rb]
+# packages/blogging/app/policies/blogging/post_policy.rb
+def permitted_attributes_for_create
+  [:user, :title, :content] # [!code --]
+  [:user, :title, :content, :comments] # [!code ++]
+end
+```
+
+:::
+
+![Plutonium Nested Comments](/tutorial/plutonium-nested-form.png)
+
+## Running the Application
+
+1. Start the Development server:
+```bash
+bin/dev
+```
+
+2. Visit `http://localhost:3000`
+
+3. Create a user account and start managing your blog!
+
+## What's Next?
+
+Some ideas for extending the application:
+- Add categories/tags for posts
+- Implement comment moderation
+- Add rich text editing for post content
+- Create a public-facing blog view
+- Add image attachments for posts
+- Implement social sharing
+
+## Conclusion
+
+In this tutorial, we've built a full-featured blog application with:
+- User authentication
+- Post management
+- Commenting system
+- Publishing workflow
+- Proper authorization
+- User-scoped content
+
+Plutonium helped us quickly scaffold and connect the pieces while maintaining clean separation of concerns through its package system.

data/docs/index.md

@@ -17,27 +17,31 @@ hero:
       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
+  # Core Value Proposition - Start with the main benefit
+  - title: Rich Resource Management
+    details: Beautiful, modern interfaces with production-ready components for rapid development
 
-  - title: Intelligent Fields
-    details: Zero-config field detection that matches your Rails models out of the box
+  # Core Architecture Features - Foundation pieces
+  - title: Built-in Multitenancy
+    details: Row-level multitenancy that works out of the box - perfect for SaaS and enterprise apps
 
-  - title: Seamless Authentication
-    details: Use your existing auth or our Rodauth integration - get setup in seconds
+  - title: Advanced Authorization
+    details: Comprehensive access control built on Action Policy's proven authorization framework
 
-  - title: Enterprise Authorization
-    details: Industrial-strength access control powered by Action Policy's proven framework
+  - title: Seamless Authentication
+    details: Integrate your existing auth or use our Rodauth integration - ready in seconds
 
-  - title: Built-in Multitenancy
-    details: Row-level multitenancy that just works - perfect for SaaS and enterprise apps
+  # Developer Experience Features - How it makes development easier
+  - title: Intelligent Fields
+    details: Smart field detection with automatic Rails model mapping and zero configuration needed
 
   - title: Advanced Nested Resources
-    details: Complex resource relationships made simple with zero extra configuration
+    details: Complex resource relationships made simple through intelligent relationship mapping
 
-  - title: Custom Actions
-    details: Extend your admin panel with incredibly simple custom actions and workflows
+  # Extensibility Features - How it grows with your needs
+  - title: Extensible Workflows
+    details: Add custom actions and business workflows with a simple, declarative API
 
-  - title: Complete Builder Control
-    details: Total flexibility to customize every aspect of your admin UI with elegant builder APIs
+  - title: Flexible UI Customization
+    details: Customize any aspect of your interfaces with elegant builder APIs
 ---

data/lib/generators/pu/gem/standard/standard_generator.rb

@@ -10,7 +10,7 @@ module Pu
       desc "Set up standardrb"
 
       def start
-        bundle "standardrb"
+        bundle "standard", version: ">= 1.35.1"
       rescue => e
         exception "#{self.class} failed:", e
       end

data/lib/plutonium/version.rb

@@ -1,5 +1,5 @@
 module Plutonium
-  VERSION = "0.15.8"
+  VERSION = "0.15.9"
   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.15.8
+  version: 0.15.9
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-07 00:00:00.000000000 Z
+date: 2024-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -1039,6 +1039,7 @@ files:
 - docs/guide/getting-started/index.md
 - docs/guide/getting-started/installation.md
 - docs/guide/getting-started/resources.md
+- docs/guide/tutorial.md
 - docs/guide/what-is-plutonium.md
 - docs/index.md
 - docs/markdown-examples.md
@@ -1052,6 +1053,15 @@ files:
 - docs/public/site.webmanifest
 - docs/public/templates/base.rb
 - docs/public/templates/plutonium.rb
+- docs/public/tutorial/plutonium-association-panel.png
+- docs/public/tutorial/plutonium-dashboard.png
+- docs/public/tutorial/plutonium-login-page.png
+- docs/public/tutorial/plutonium-nested-form.png
+- docs/public/tutorial/plutonium-posts-dashboard-customized.png
+- docs/public/tutorial/plutonium-posts-dashboard.png
+- docs/public/tutorial/plutonium-posts-detail-customized.png
+- docs/public/tutorial/plutonium-posts-detail.png
+- docs/public/tutorial/plutonium-publish-post.png
 - esbuild.config.js
 - exe/pug
 - gemfiles/rails_7.gemfile