plutonium 0.33.1 → 0.34.0

data/.claude/skills/forms/SKILL.md

@@ -0,0 +1,439 @@
+---
+name: forms
+description: Plutonium forms - custom templates, Phlex form components, field builders, and theming
+---
+
+# Plutonium Forms
+
+Plutonium forms are built on [Phlexi::Form](https://github.com/radioactive-labs/phlexi-form), providing a Ruby-first approach to form building with Phlex components.
+
+## Form Class Hierarchy
+
+```
+Phlexi::Form::Base
+└── Plutonium::UI::Form::Base       # Base with Plutonium components
+    ├── Plutonium::UI::Form::Resource   # Resource CRUD forms
+    │   └── Plutonium::UI::Form::Interaction  # Interactive action forms
+    └── Plutonium::UI::Form::Query      # Search/filter forms
+```
+
+## Customizing Resource Forms
+
+### Override in Definition
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Form < Form
+    def form_template
+      # Your custom form layout
+      render_fields
+      render_actions
+    end
+  end
+end
+```
+
+### Form Template Methods
+
+| Method | Description |
+|--------|-------------|
+| `form_template` | Main template method to override |
+| `render_fields` | Render all permitted fields |
+| `render_resource_field(name)` | Render a single field by name |
+| `render_actions` | Render submit buttons |
+| `fields_wrapper { }` | Wrapper div for field grid |
+| `actions_wrapper { }` | Wrapper div for buttons |
+
+### Form Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `object` / `record` | The form object being edited |
+| `resource_fields` | Array of permitted field names |
+| `resource_definition` | The definition instance |
+
+## Custom Form Layout
+
+### Sectioned Form
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Form < Form
+    def form_template
+      section("Basic Information") {
+        render_resource_field :title
+        render_resource_field :slug
+      }
+
+      section("Content") {
+        render_resource_field :content
+        render_resource_field :excerpt
+      }
+
+      section("Publishing") {
+        render_resource_field :published_at
+        render_resource_field :category
+      }
+
+      render_actions
+    end
+
+    private
+
+    def section(title, &)
+      div(class: "mb-8") {
+        h3(class: "text-lg font-semibold mb-4 text-gray-900 dark:text-white") { title }
+        fields_wrapper(&)
+      }
+    end
+  end
+end
+```
+
+### Two-Column Layout
+
+```ruby
+class Form < Form
+  def form_template
+    div(class: "grid grid-cols-1 lg:grid-cols-3 gap-6") {
+      # Main content - 2 columns
+      div(class: "lg:col-span-2") {
+        fields_wrapper {
+          render_resource_field :title
+          render_resource_field :content
+        }
+      }
+
+      # Sidebar - 1 column
+      div(class: "space-y-4") {
+        Panel {
+          h4(class: "font-medium mb-2") { "Settings" }
+          render_resource_field :status
+          render_resource_field :visibility
+        }
+      }
+    }
+
+    render_actions
+  end
+end
+```
+
+## Field Builder
+
+When using `render_resource_field`, Plutonium uses the field builder. For custom rendering, use the `field` method directly.
+
+### Basic Field Usage
+
+```ruby
+def form_template
+  # Using field builder directly
+  render field(:title).wrapped {|f| f.input_tag }
+  render field(:content).wrapped {|f| f.easymde_tag }
+  render field(:published).wrapped {|f| f.checkbox_tag }
+
+  render_actions
+end
+```
+
+### Field Builder Methods
+
+The field builder (`f`) provides these tag methods:
+
+| Method | Input Type |
+|--------|------------|
+| `f.input_tag` | Text input (auto-detects type) |
+| `f.string_tag` | Text input |
+| `f.text_tag` | Textarea |
+| `f.number_tag` | Number input |
+| `f.email_tag` | Email input |
+| `f.password_tag` | Password input |
+| `f.url_tag` | URL input |
+| `f.tel_tag` | Telephone input |
+| `f.hidden_tag` | Hidden input |
+| `f.checkbox_tag` | Checkbox |
+| `f.select_tag` | Select dropdown |
+| `f.radio_button_tag` | Radio buttons |
+
+### Plutonium-Enhanced Tags
+
+| Method | Description |
+|--------|-------------|
+| `f.easymde_tag` / `f.markdown_tag` | Markdown editor (EasyMDE) |
+| `f.slim_select_tag` | Enhanced select (Slim Select) |
+| `f.flatpickr_tag` | Date/time picker (Flatpickr) |
+| `f.phone_tag` / `f.int_tel_input_tag` | International phone input |
+| `f.uppy_tag` / `f.file_tag` | File upload (Uppy) |
+| `f.secure_association_tag` | Association with authorization |
+| `f.belongs_to_tag` | Belongs-to association |
+| `f.has_many_tag` | Has-many association |
+| `f.has_one_tag` | Has-one association |
+| `f.key_value_store_tag` | Key-value pairs |
+
+### Field with Options
+
+```ruby
+# Select with choices
+render field(:status).wrapped { |f|
+  f.select_tag(choices: %w[draft published archived])
+}
+
+# Date picker with options
+render field(:published_at).wrapped { |f|
+  f.flatpickr_tag(min_date: Date.today, enable_time: true)
+}
+
+# File upload with restrictions
+render field(:avatar).wrapped { |f|
+  f.uppy_tag(
+    allowed_file_types: %w[.jpg .png .gif],
+    max_file_size: 5.megabytes
+  )
+}
+```
+
+### Wrapped vs Unwrapped
+
+```ruby
+# Wrapped - includes label, hint, errors
+render field(:title).wrapped { |f| f.input_tag }
+
+# Unwrapped - just the input element
+render field(:title).input_tag
+
+# Custom wrapper options
+render field(:title).wrapped(class: "col-span-full") { |f|
+  f.input_tag
+}
+```
+
+## Input Configuration in Definitions
+
+Define inputs in the definition, render them in the form:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Configure inputs
+  input :title, hint: "Be descriptive", placeholder: "Enter title"
+  input :content, as: :markdown
+  input :status, as: :select, choices: %w[draft published]
+  input :published_at, as: :flatpickr
+
+  # Custom input with block
+  input :category do |f|
+    choices = Category.active.pluck(:name, :id)
+    f.select_tag(choices: choices)
+  end
+
+  class Form < Form
+    def form_template
+      # render_resource_field uses the input configuration
+      render_resource_field :title
+      render_resource_field :content
+      render_resource_field :status
+      render_resource_field :published_at
+      render_resource_field :category
+
+      render_actions
+    end
+  end
+end
+```
+
+## Dynamic Forms (pre_submit)
+
+Fields with `pre_submit: true` trigger form re-rendering on change:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  input :post_type, as: :select,
+    choices: %w[article video podcast],
+    pre_submit: true
+
+  input :video_url,
+    condition: -> { object.post_type == "video" }
+
+  input :podcast_url,
+    condition: -> { object.post_type == "podcast" }
+end
+```
+
+When `post_type` changes, the form re-renders via Turbo and shows/hides conditional fields.
+
+## Nested Forms
+
+For `has_many` / `has_one` associations with `accepts_nested_attributes_for`:
+
+### Model Setup
+
+```ruby
+class Post < ResourceRecord
+  has_many :comments
+  accepts_nested_attributes_for :comments, allow_destroy: true
+end
+```
+
+### Definition Setup
+
+```ruby
+class PostDefinition < ResourceDefinition
+  nested_input :comments do |n|
+    n.input :author_name
+    n.input :body, as: :text
+  end
+
+  # Or reference another definition
+  nested_input :comments, using: CommentDefinition, fields: %i[author_name body]
+end
+```
+
+### Custom Nested Rendering
+
+```ruby
+class Form < Form
+  def form_template
+    render_resource_field :title
+    render_resource_field :content
+
+    # Nested fields are automatically handled
+    render_resource_field :comments
+
+    render_actions
+  end
+end
+```
+
+## Interaction Forms
+
+Forms for interactive actions use `Plutonium::UI::Form::Interaction`:
+
+```ruby
+class PublishPostInteraction < ResourceInteraction
+  attribute :publish_date, :date
+  attribute :notify_subscribers, :boolean, default: true
+
+  # Custom form
+  class Form < Form
+    def form_template
+      div(class: "space-y-4") {
+        render_resource_field :publish_date
+        render_resource_field :notify_subscribers
+      }
+      render_actions
+    end
+  end
+end
+```
+
+## Form Actions
+
+### Default Actions
+
+```ruby
+def render_actions
+  actions_wrapper {
+    # "Create and add another" / "Update and continue editing" button
+    # Primary submit button
+    render submit_button
+  }
+end
+```
+
+### Custom Actions
+
+```ruby
+def render_actions
+  actions_wrapper {
+    # Cancel link
+    a(href: resource_url_for(resource_class), class: "btn btn-secondary") {
+      "Cancel"
+    }
+
+    # Save as draft
+    button(type: :submit, name: "draft", value: "1", class: "btn") {
+      "Save Draft"
+    }
+
+    # Primary submit
+    render submit_button
+  }
+end
+```
+
+## Form Context
+
+Inside form templates, you have access to:
+
+```ruby
+class Form < Form
+  def form_template
+    # Form object
+    object              # The record
+    record              # Alias for object
+    object.new_record?  # Check if creating
+
+    # Request context
+    current_user
+    current_parent
+    current_scoped_entity
+    request
+    params
+
+    # Definition
+    resource_definition
+    resource_fields     # Permitted fields
+
+    # URL helpers
+    resource_url_for(object)
+    resource_url_for(Post, action: :new)
+
+    # Rails helpers
+    helpers.link_to(...)
+  end
+end
+```
+
+## Theming
+
+Forms use a theme system for consistent styling:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Form < Form
+    class Theme < Plutonium::UI::Form::Theme
+      def self.theme
+        super.merge({
+          fields_wrapper: "grid grid-cols-2 gap-6",
+          actions_wrapper: "flex justify-between mt-8",
+          input: "w-full p-3 border-2 rounded-lg",
+          label: "block mb-1 font-bold text-gray-700"
+        })
+      end
+    end
+  end
+end
+```
+
+### Theme Keys
+
+| Key | Description |
+|-----|-------------|
+| `base` | Form container |
+| `fields_wrapper` | Grid wrapper for fields |
+| `actions_wrapper` | Wrapper for buttons |
+| `wrapper` | Individual field wrapper |
+| `label` | Label styling |
+| `input` | Input styling |
+| `hint` | Hint text styling |
+| `error` | Error message styling |
+| `button` | Submit button styling |
+| `checkbox` | Checkbox styling |
+| `select` | Select styling |
+
+## Related Skills
+
+- `definition-fields` - Input configuration (as:, hint:, condition:)
+- `views` - Custom page classes
+- `assets` - TailwindCSS and component theming
+- `interaction` - Interactive action forms
+- `nested-resources` - Parent/child forms

data/.claude/skills/installation/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: installation
+description: Installing Plutonium in a Rails application - setup, generators, and configuration
+---
+
+# Plutonium Installation
+
+## New Rails App (Recommended)
+
+Use the Rails template for a fully configured setup:
+
+```bash
+rails new myapp -a propshaft -j esbuild -c tailwind \
+  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+```
+
+This sets up Rails with Propshaft, esbuild, TailwindCSS, and Plutonium in one command.
+
+## Existing Rails App
+
+### Option 1: Rails Template
+
+```bash
+bin/rails app:template \
+  LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
+```
+
+### Option 2: Manual Installation
+
+```bash
+# Add to Gemfile
+gem "plutonium"
+
+# Install
+bundle install
+rails generate pu:core:install
+```
+
+## What Gets Generated
+
+After `pu:core:install`:
+
+```
+app/
+├── controllers/
+│   ├── plutonium_controller.rb    # Base controller
+│   └── resource_controller.rb     # Resource CRUD base
+├── definitions/
+│   └── resource_definition.rb     # Definition base class
+├── interactions/
+│   └── resource_interaction.rb    # Interaction base class
+├── models/
+│   └── resource_record.rb         # Abstract model base
+├── policies/
+│   └── resource_policy.rb         # Policy base class
+└── views/
+    └── layouts/
+        └── resource.html.erb      # Base layout
+
+config/
+├── initializers/
+│   └── plutonium.rb               # Configuration
+└── packages.rb                    # Package loader
+
+packages/
+└── .keep
+```
+
+## Base Classes
+
+### ResourceController
+
+```ruby
+class ResourceController < PlutoniumController
+  include Plutonium::Resource::Controller
+  # Provides: index, show, new, create, edit, update, destroy
+  # Plus: interactive actions, authorization, query handling
+end
+```
+
+### ResourcePolicy
+
+```ruby
+class ResourcePolicy < Plutonium::Resource::Policy
+  def create?
+    true  # Override with your logic
+  end
+
+  def read?
+    true
+  end
+end
+```
+
+### ResourceDefinition
+
+```ruby
+class ResourceDefinition < Plutonium::Resource::Definition
+  # Add app-wide definition defaults here
+end
+```
+
+### ResourceRecord
+
+```ruby
+class ResourceRecord < ApplicationRecord
+  self.abstract_class = true
+  # Models inherit from this for Plutonium features
+end
+```
+
+## Authentication Setup
+
+### Install Rodauth
+
+```bash
+rails generate pu:rodauth:install
+```
+
+### Create Account Types
+
+```bash
+# Basic user account
+rails generate pu:rodauth:account user
+
+# Admin with 2FA, lockout, audit logging
+rails generate pu:rodauth:admin
+
+# Customer with entity association
+rails generate pu:rodauth:customer customer
+```
+
+### Account Options
+
+| Option | Description |
+|--------|-------------|
+| `--defaults` | Enable common features (login, logout, remember, reset_password) |
+| `--kitchen_sink` | Enable all available features |
+| `--no-allow_signup` | Disable public signup |
+| `--entity=Organization` | Create associated entity model |
+
+### Connect Auth to Controllers
+
+```ruby
+# app/controllers/resource_controller.rb
+class ResourceController < PlutoniumController
+  include Plutonium::Resource::Controller
+  include Plutonium::Auth::Rodauth(:user)  # Add this
+end
+```
+
+## Creating Your First Resource
+
+```bash
+rails generate pu:res:scaffold Post user:belongs_to title:string content:text
+rails db:migrate
+```
+
+## Creating a Portal
+
+```bash
+rails generate pu:pkg:portal admin
+```
+
+Select authentication when prompted:
+- **Rodauth account** - Use existing auth
+- **Public access** - No authentication
+- **Bring your own** - Custom implementation
+
+### Mount the Portal
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount AdminPortal::Engine, at: "/admin"
+end
+```
+
+### Connect Resources to Portal
+
+```bash
+rails generate pu:res:conn Post --dest=admin_portal
+```
+
+## Configuration
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure do |config|
+  config.load_defaults 1.0
+
+  # Custom assets (optional)
+  # config.assets.stylesheet = "custom_stylesheet"
+  # config.assets.script = "custom_script"
+  # config.assets.logo = "custom_logo.png"
+end
+```
+
+## Package System
+
+Packages are loaded from `config/packages.rb`:
+
+```ruby
+Dir.glob(File.expand_path("../packages/**/lib/engine.rb", __dir__)) { |package| load package }
+```
+
+Create packages in `packages/` directory:
+- **Feature packages** - Business logic (`rails g pu:pkg:package blogging`)
+- **Portal packages** - Web interfaces (`rails g pu:pkg:portal admin`)
+
+## Post-Installation Checklist
+
+1. **Install core**
+   ```bash
+   rails generate pu:core:install
+   ```
+
+2. **Setup authentication** (if needed)
+   ```bash
+   rails generate pu:rodauth:install
+   rails generate pu:rodauth:account user
+   ```
+
+3. **Create a portal**
+   ```bash
+   rails generate pu:pkg:portal admin
+   ```
+
+4. **Create resources**
+   ```bash
+   rails generate pu:res:scaffold Post title:string content:text
+   ```
+
+5. **Connect resources to portal**
+   ```bash
+   rails generate pu:res:conn Post --dest=admin_portal
+   ```
+
+6. **Run migrations**
+   ```bash
+   rails db:migrate
+   ```
+
+7. **Mount portal** (add to `config/routes.rb`)
+   ```ruby
+   mount AdminPortal::Engine, at: "/admin"
+   ```
+
+8. **Start server**
+   ```bash
+   rails server
+   ```
+
+## Converting Existing Models
+
+For models that already exist in your app:
+
+1. Include the module:
+   ```ruby
+   class Post < ApplicationRecord
+     include Plutonium::Resource::Record
+   end
+   ```
+
+2. Generate supporting files (skips model/migration):
+   ```bash
+   rails g pu:res:scaffold Post
+   ```
+
+3. Connect to portal:
+   ```bash
+   rails g pu:res:conn Post --dest=admin_portal
+   ```
+
+## Generator Reference
+
+| Generator | Purpose |
+|-----------|---------|
+| `pu:core:install` | Initial Plutonium setup |
+| `pu:rodauth:install` | Setup Rodauth authentication |
+| `pu:rodauth:account NAME` | Create user account type |
+| `pu:rodauth:admin` | Create admin account with 2FA |
+| `pu:rodauth:customer NAME` | Create customer with entity |
+| `pu:pkg:package NAME` | Create feature package |
+| `pu:pkg:portal NAME` | Create portal package |
+| `pu:res:scaffold NAME` | Create resource (model, policy, definition, controller) |
+| `pu:res:conn NAME` | Connect resource to portal |
+| `pu:eject:layout` | Eject layout files for customization |
+| `pu:skills:sync` | Sync Claude Code skills to project |
+
+## Related Skills
+
+- `resource` - Resource architecture overview
+- `rodauth` - Authentication setup and configuration
+- `package` - Feature and portal packages
+- `portal` - Portal configuration
+- `views` - Custom pages, layouts, and Phlex components
+- `assets` - TailwindCSS and custom styling
+- `create-resource` - Resource scaffold options
+- `connect-resource` - Portal connection