plutonium 0.33.0 → 0.34.0

data/docs/guide/deep-dive/resources.md

@@ -1,390 +0,0 @@
-# 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 '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 published_at]
-  end
-
-  def permitted_attributes_for_read
-    %i[user title content 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, wrapper: {class: "col-span-full"}
-  display :content, wrapper: {class: "col-span-full"} do |f|
-    f.text_tag class: "format dark:format-invert"
-  end
-
-  # Custom column display in tables
-  column :published_at, align: :end
-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(
-        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 :published_at,
-    with: DateFilter,
-    predicate: :gteq
-
-  # Add scopes
-  scope :published do |scope|
-    scope.where.not(published_at: nil)
-  end
-  scope :draft do |scope|
-    scope.where(published_at: nil)
-  end
-
-  # Configure sorting
-  sort :title
-  sort :published_at
-  
-  # Configure default sorting (newest first)
-  default_sort :published_at, :desc
-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
-:::
-
-# Deep Dive: Building a Resource
-
-In Plutonium, a **Resource** is the central concept for managing your application's data. It's more than just a model—it's a complete package that includes the model, controller, policy, views, and all the configuration that ties them together.
-
-This guide will walk you through building a complete `Post` resource from scratch, demonstrating how Plutonium's different modules work together to create a powerful and consistent user experience.
-
-## 1. Generating the Resource
-
-We'll start with the scaffold generator, which creates all the necessary files for our `Post` resource.
-
-```bash
-rails generate pu:res:scaffold Post user:belongs_to title:string content:text published_at:datetime
-```
-
-This command generates:
-- A `Post` model with the specified attributes and a `belongs_to :user` association.
-- A `PostsController`.
-- A `PostPolicy` with basic permissions.
-- A `PostDefinition` file, which will be the focus of this guide.
-
-## 2. Configuring Display & Forms (The Definition File)
-
-The **Definition** file (`app/definitions/post_definition.rb`) is where you declaratively configure how your resource is displayed and edited. Let's start by defining the fields for our table, detail page, and form.
-
-::: code-group
-```ruby [app/definitions/post_definition.rb]
-class PostDefinition < Plutonium::Resource::Definition
-  # Configure the table (index view)
-  column :user, label: "Author"
-  column :published_at, as: :datetime
-
-  # Configure the detail page (show view)
-  display :user, label: "Author"
-  display :published_at, as: :datetime
-  display :content, as: :rich_text
-
-  # Configure the form (new/edit views)
-  input :user, as: :select, label: "Author" # Explicitly use a select input
-  input :content, as: :rich_text
-end
-```
-```ruby [app/policies/post_policy.rb]
-# In the policy, we must permit these attributes to be read and written.
-class PostPolicy < Plutonium::Resource::Policy
-  # ...
-
-  def permitted_attributes_for_read
-    [:title, :user, :published_at, :content]
-  end
-
-  def permitted_attributes_for_create
-    [:title, :user_id, :content]
-  end
-
-  def permitted_attributes_for_update
-    permitted_attributes_for_create
-  end
-end
-```
-:::
-
-Here, we've used the `display` helper to control the `index` and `show` views, and the `input` helper for the forms. We've also specified `:rich_text` to get a WYSIWYG editor for our content. Notice that we also had to permit these attributes in the policy.
-
-## 3. Adding a Custom Action
-
-Standard CRUD is great, but most applications have custom business logic. Let's add a "Publish" action. This involves creating an **Interaction** for the logic and registering it in the definition.
-
-::: code-group
-```ruby [app/interactions/post_interactions/publish.rb]
-module PostInteractions
-  class Publish < Plutonium::Resource::Interaction
-    attribute :resource, class: "Post"
-
-    private
-
-    def execute
-      resource.update(published_at: Time.current)
-      succeed(resource).with_message("Post was successfully published.")
-    end
-  end
-end
-```
-```ruby [app/definitions/post_definition.rb]
-class PostDefinition < Plutonium::Resource::Definition
-  # ... (display and input helpers)
-
-  action :publish,
-    interaction: "PostInteractions::Publish",
-    category: :primary
-end
-```
-```ruby [app/policies/post_policy.rb]
-class PostPolicy < Plutonium::Resource::Policy
-  # ... (attribute permissions)
-
-  # An action is only visible if its policy returns true.
-  def publish?
-    # Only show the publish button if the post is not yet published.
-    update? && record.published_at.nil?
-  end
-end
-```
-:::
-
-We now have a "Publish" button on our `Post` detail page that only appears when appropriate, thanks to the combination of the Interaction, Definition, and Policy.
-
-## 4. Configuring Search, Filters, and Sorting
-
-To make our resource table more useful, let's add search, filtering, and sorting capabilities. This is all handled declaratively in the definition file.
-
-```ruby
-# app/definitions/post_definition.rb
-class PostDefinition < Plutonium::Resource::Definition
-  # ... (display, input, and action helpers)
-
-  # Enable full-text search across title and content
-  search do |scope, query|
-    scope.where("title ILIKE :q OR content ILIKE :q", q: "%#{query}%")
-  end
-
-  # Add filters to the sidebar
-  filter :published, with: ->(scope, value) { value ? scope.where.not(published_at: nil) : scope.where(published_at: nil) }, as: :boolean
-  filter :user, as: :select, choices: User.pluck(:name, :id)
-
-  # Define named scopes that appear as buttons
-  scope :all
-  scope :published, -> { where.not(published_at: nil) }
-  scope :drafts, -> { where(published_at: nil) }
-
-  # Configure which columns are sortable
-  sort :title
-  sort :published_at
-end
-```
-
-With just a few lines of code, we now have a powerful and interactive table view for our posts, complete with a search bar, filter sidebar, scope buttons, and sortable columns. This demonstrates how the **Resource** module integrates seamlessly with the **Query** module.

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

@@ -1,165 +0,0 @@
-# Installation and Setup
-
-::: tip VERSION REQUIREMENTS
-- Ruby 3.2.2 or higher
-- Rails 7.1 or higher
-- Node.js and Yarn
-:::
-
-## 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`.
-:::
-
-## 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:annotated
-
-# Set up environment variables
-rails generate pu:gem:dotenv
-```

data/docs/guide/index.md

@@ -1,28 +0,0 @@
----
-layout: home
-title: Plutonium Documentation
-hero:
-  name: Plutonium Documentation
-  text: A RAD toolkit for Rails
-  tagline: Build better applications, faster.
-  actions:
-    - theme: brand
-      text: Get Started
-      link: /guide/introduction/01-what-is-plutonium
-    - theme: alt
-      text: View on GitHub
-      link: https://github.com/radioactive-labs/plutonium
-features:
-  - title: Introduction
-    details: Learn about the core concepts and architecture of Plutonium.
-    link: /guide/introduction/01-what-is-plutonium
-  - title: Tutorial
-    details: A step-by-step guide to building your first application.
-    link: /guide/tutorial/01-project-setup
-  - title: Deep Dive Guides
-    details: In-depth explanations of specific Plutonium features.
-    link: /guide/deep-dive/resources
-  - title: Module Documentation
-    details: Detailed documentation for each Plutonium module.
-    link: /modules/
----