plutonium 0.15.4 → 0.15.6

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

@@ -0,0 +1,18 @@
+# Getting Started with Plutonium
+
+<!--
+This guide covers getting up and running with Plutonium.
+
+After reading this guide, you will know:
+
+- How to install Plutonium.
+- The general layout of a Plutonium application.
+- The basic principles of Resource design.
+- How to quickly generate the starting pieces of a Plutonium application.
+-->
+
+## Prerequisites
+
+Before using Plutonium, you should be familiar with Rails.
+Plutonium builds upon many core Rails concepts and conventions.
+If you're new to Rails or need a refresher, we highly recommend reading the [Rails' guide](https://guides.rubyonrails.org/getting_started.html).

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

@@ -0,0 +1,269 @@
+# Installation and Setup
+
+::: tip VERSION REQUIREMENTS
+- Ruby 3.2.2 or higher
+- Rails 7.1 or higher
+:::
+
+## Quick Start
+
+Get up and running with Plutonium in seconds:
+
+::: code-group
+```bash [New App]
+rails new plutonium_app -a propshaft -j esbuild -c tailwind \
+  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+```
+
+```bash [Existing App]
+bin/rails app:template \
+  LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
+```
+:::
+
+## Detailed Installation Guide
+
+1. Add Plutonium to your Gemfile:
+
+::: code-group
+```ruby [Gemfile]
+gem "plutonium"
+```
+
+```bash [Terminal]
+bundle install
+```
+:::
+
+2. Run the installation generator:
+
+```bash
+rails generate pu:core:install
+```
+
+This will:
+- Set up the basic Plutonium structure
+- Create necessary configuration files
+- Configure your application for Plutonium
+
+### Project Structure
+
+After installation, your project will have the following new directories and files:
+
+```
+my_rails_app/
+├── app/
+│   ├── controllers/
+│   │   ├── plutonium_controller.rb     # Base controller for Plutonium
+│   │   └── resource_controller.rb      # Base controller for resources
+│   ├── definitions/
+│   │   └── resource_definition.rb      # Base class for resource definitions
+│   ├── interactions/
+│   │   └── resource_interaction.rb     # Base class for resource interactions
+│   ├── models/
+│   │   └── resource_record.rb         # Base module for resource models
+│   ├── policies/
+│   │   └── resource_policy.rb         # Base class for resource policies
+│   └── views/
+│       └── layouts/
+│           └── resource.html.erb       # Base layout for resources
+├── config/
+│   ├── initializers/
+│   │   └── plutonium.rb               # Main configuration
+│   └── packages.rb                    # Package registration
+└── packages/                          # Directory for modular features
+    └── .keep
+```
+
+## Configuration
+
+### Basic Configuration
+
+Configure Plutonium in `config/initializers/plutonium.rb`:
+
+```ruby
+Plutonium.configure do |config|
+  # Load default configuration for version 1.0
+  config.load_defaults 1.0
+
+  # Asset configuration
+  config.assets.stylesheet = "plutonium.css" # Default stylesheet
+  config.assets.script = "plutonium.js"     # Default JavaScript
+  config.assets.logo = "plutonium.png"   # Default logo
+end
+```
+
+### Authentication Setup
+
+Plutonium supports multiple authentication strategies. Here's how to set up the recommended Rodauth integration:
+
+1. Install Rodauth:
+
+```bash
+rails generate pu:rodauth:install
+```
+
+2. Create an authentication account:
+
+::: code-group
+```bash [Basic Setup]
+rails generate pu:rodauth:account user
+```
+
+```bash [Custom Setup]
+# Include selected authentication features
+rails generate pu:rodauth:account admin --no-defaults \
+  --login --logout --remember --lockout \
+  --create-account --verify-account --close-account \
+   --change-password --reset-password --reset-password-notify \
+  --active-sessions --password-grace-period --otp \
+  --recovery-codes --audit-logging --internal-request
+```
+:::
+
+3. Configure the authentication controller:
+
+```ruby
+# app/controllers/resource_controller.rb
+class ResourceController < PlutoniumController
+  include Plutonium::Resource::Controller
+  include Plutonium::Auth::Rodauth(:user)
+end
+```
+
+::: tip
+You can use your existing authentication system by implementing the `current_user` method in `ResourceController`.
+:::
+
+<!--
+## Asset Pipeline Setup
+
+### JavaScript Setup
+
+
+Plutonium uses modern JavaScript features. Here's how to set it up:
+
+1. Install required npm packages:
+
+::: code-group
+```bash [importmap]
+bin/importmap pin @radioactive-labs/plutonium
+```
+
+```bash [esbuild]
+npm install @radioactive-labs/plutonium
+```
+:::
+
+
+2. Configure JavaScript:
+
+::: code-group
+```js [app/javascript/controllers/index.js]
+import { application } from "controllers/application"
+import { registerControllers } from "@radioactive-labs/plutonium" // [!code ++]
+registerControllers(application) // [!code ++]
+```
+
+```js [app/javascript/application.js]
+import "@hotwired/turbo-rails"
+import "controllers"
+```
+:::
+
+### CSS Setup
+
+Plutonium uses Tailwind CSS. Configure it in your `tailwind.config.js`:
+
+```js
+const defaultTheme = require('tailwindcss/defaultTheme')
+
+module.exports = {
+  content: [
+    './app/views/**/*.erb',
+    './app/helpers/**/*.rb',
+    './app/javascript/**/*.js',
+    './app/components/**/*.{erb,rb}',
+    './node_modules/@radioactive-labs/plutonium/**/*.{js,ts}'
+  ],
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['Inter var', ...defaultTheme.fontFamily.sans],
+      },
+    },
+  },
+  plugins: [
+    require('@tailwindcss/forms'),
+    require('flowbite/plugin')
+  ],
+}
+```
+-->
+
+## Optional Enhancements
+
+### Database Performance
+
+For PostgreSQL/MySQL users, add these recommended gems:
+
+```ruby
+group :development, :test do
+  # N+1 query detection
+  gem "prosopite"
+end
+
+# Automatic eager loading
+gem "goldiloader"
+```
+
+### Development Tools
+
+Add helpful development gems:
+
+```ruby
+# Generate model annotations
+rails generate pu:gem:annotate
+
+# Set up environment variables
+rails generate pu:gem:dotenv
+```
+
+<!--
+## Verification
+
+Verify your installation:
+
+```bash
+# Start your Rails server
+rails server
+
+# Check your logs for any warnings or errors
+tail -f log/development.log
+
+# Generate and test a sample resource
+rails generate pu:res:scaffold Post title:string content:text
+```
+
+Visit `http://localhost:3000/posts` to verify everything is working.
+-->
+
+<!--
+::: tip Next Steps
+Now that you have Plutonium installed and configured, you're ready to:
+1. [Create your first resource](/guide/resources/creating-resources)
+2. [Set up your first package](/guide/packages/creating-packages)
+3. [Configure authorization](/guide/authorization/basic-setup)
+:::
+-->
+
+<!--
+### Getting Help
+
+If you run into issues:
+
+1. Check the [FAQ](/guide/faq)
+2. Search [GitHub Issues](https://github.com/radioactive-labs/plutonium-core/issues)
+3. Join our [Discord Community](https://discord.gg/plutonium)
+4. Create a new [GitHub Issue](https://github.com/radioactive-labs/plutonium-core/issues/new)
+-->

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
+:::