plutonium 0.33.1 → 0.34.0

data/docs/guides/search-filtering.md

@@ -0,0 +1,266 @@
+# Search and Filtering
+
+This guide covers implementing search, filters, scopes, and sorting.
+
+## Overview
+
+Plutonium provides built-in support for:
+- **Search** - Full-text search across fields
+- **Filters** - Input filters for specific fields
+- **Scopes** - Predefined query shortcuts (quick filter buttons)
+- **Sorting** - Column-based ordering
+
+## Search
+
+Define global search in the definition:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  search do |scope, query|
+    scope.where("title ILIKE ?", "%#{query}%")
+  end
+end
+```
+
+### Multi-Field Search
+
+```ruby
+search do |scope, query|
+  scope.where(
+    "title ILIKE :q OR content ILIKE :q OR author_name ILIKE :q",
+    q: "%#{query}%"
+  )
+end
+```
+
+### Search with Associations
+
+```ruby
+search do |scope, query|
+  scope.joins(:author).where(
+    "posts.title ILIKE :q OR users.name ILIKE :q",
+    q: "%#{query}%"
+  ).distinct
+end
+```
+
+### Split Search Terms
+
+```ruby
+search do |scope, query|
+  terms = query.split(/\s+/)
+  terms.reduce(scope) do |current_scope, term|
+    current_scope.where("title ILIKE ?", "%#{term}%")
+  end
+end
+```
+
+### Full-Text Search (PostgreSQL)
+
+```ruby
+search do |scope, query|
+  scope.where(
+    "to_tsvector('english', title || ' ' || body) @@ plainto_tsquery('english', ?)",
+    query
+  )
+end
+```
+
+## Filters
+
+Filters provide UI controls for narrowing results.
+
+### Text Filter
+
+The built-in `Text` filter supports various predicates:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Exact match
+  filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
+
+  # Contains (LIKE %value%)
+  filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
+
+  # Starts with
+  filter :slug, with: Plutonium::Query::Filters::Text, predicate: :starts_with
+
+  # Ends with
+  filter :email, with: Plutonium::Query::Filters::Text, predicate: :ends_with
+end
+```
+
+### Available Predicates
+
+| Predicate | SQL | Description |
+|-----------|-----|-------------|
+| `:eq` | `= value` | Exact match |
+| `:not_eq` | `!= value` | Not equal |
+| `:contains` | `LIKE %value%` | Contains text |
+| `:not_contains` | `NOT LIKE %value%` | Does not contain |
+| `:starts_with` | `LIKE value%` | Starts with |
+| `:ends_with` | `LIKE %value` | Ends with |
+| `:matches` | `LIKE value` | Pattern match (`*` becomes `%`) |
+| `:not_matches` | `NOT LIKE value` | Does not match pattern |
+
+### Custom Filter with Lambda
+
+```ruby
+filter :published, with: ->(scope, value) {
+  value == "true" ? scope.where.not(published_at: nil) : scope.where(published_at: nil)
+}
+
+filter :has_comments, with: ->(scope, value) {
+  if value == "true"
+    scope.joins(:comments).distinct
+  else
+    scope.left_joins(:comments).where(comments: { id: nil })
+  end
+}
+```
+
+### Custom Filter Class
+
+```ruby
+class DateRangeFilter < Plutonium::Query::Filter
+  def apply(scope, start_date: nil, end_date: nil)
+    scope = scope.where("#{key} >= ?", start_date.beginning_of_day) if start_date.present?
+    scope = scope.where("#{key} <= ?", end_date.end_of_day) if end_date.present?
+    scope
+  end
+
+  def customize_inputs
+    input :start_date, as: :date
+    input :end_date, as: :date
+  end
+end
+
+# Use in definition
+filter :created_at, with: DateRangeFilter
+```
+
+## Scopes
+
+Scopes appear as quick filter buttons. They reference model scopes or use inline blocks.
+
+### Basic Scopes
+
+Reference existing model scopes:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  scope :published    # Uses Post.published
+  scope :draft        # Uses Post.draft
+  scope :featured     # Uses Post.featured
+end
+```
+
+### Inline Scopes
+
+Use block syntax with the scope passed as an argument:
+
+```ruby
+scope(:recent) { |scope| scope.where("created_at > ?", 1.week.ago) }
+scope(:this_month) { |scope| scope.where(created_at: Time.current.all_month) }
+```
+
+### With Controller Context
+
+Inline scopes have access to controller context like `current_user`:
+
+```ruby
+scope(:mine) { |scope| scope.where(author: current_user) }
+scope(:my_team) { |scope| scope.where(team: current_user.team) }
+```
+
+### Default Scope
+
+Set a scope as default:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  scope :published, default: true  # Applied by default
+  scope :draft
+  scope :archived
+end
+```
+
+When a default scope is set:
+- The default scope is applied on initial page load
+- The default scope button is highlighted (not "All")
+- Clicking "All" shows all records without any scope filter
+
+## Sorting
+
+### Define Sortable Fields
+
+```ruby
+class PostDefinition < ResourceDefinition
+  sort :title
+  sort :created_at
+  sort :view_count
+
+  # Multiple at once
+  sorts :title, :created_at, :view_count
+end
+```
+
+### Default Sort Order
+
+```ruby
+# Field and direction
+default_sort :created_at, :desc
+default_sort :title, :asc
+
+# Complex sorting with block
+default_sort { |scope| scope.order(featured: :desc, created_at: :desc) }
+```
+
+**Note:** Default sort only applies when no sort params are provided. The system default is `:id, :desc`.
+
+## URL Parameters
+
+Query parameters are structured under `q`:
+
+```
+/posts?q[search]=rails
+/posts?q[status][query]=published
+/posts?q[scope]=recent
+/posts?q[sort_fields][]=created_at&q[sort_directions][created_at]=desc
+```
+
+## Complete Example
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Full-text search
+  search do |scope, query|
+    scope.where(
+      "title ILIKE :q OR content ILIKE :q",
+      q: "%#{query}%"
+    )
+  end
+
+  # Filters
+  filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
+  filter :category, with: Plutonium::Query::Filters::Text, predicate: :eq
+  filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
+
+  # Quick scopes (reference model scopes)
+  scope :published
+  scope :draft
+  scope :featured
+  scope(:recent) { |scope| scope.where("created_at > ?", 1.week.ago) }
+
+  # Sortable columns
+  sorts :title, :created_at, :view_count, :published_at
+
+  # Default: newest first
+  default_sort :created_at, :desc
+end
+```
+
+## Related
+
+- [Custom Actions](./custom-actions)
+- [Authorization](./authorization)

data/docs/guides/theming.md

@@ -0,0 +1,321 @@
+# Theming
+
+This guide covers customizing colors, styles, and branding.
+
+## Overview
+
+Plutonium uses TailwindCSS 4 for styling. Customization happens through:
+
+- **Tailwind Configuration** - Extend colors and design tokens
+- **Component Themes** - Override form, table, and display styling
+- **Asset Configuration** - Custom CSS, JS, logo, and favicon
+
+## Setup Custom Assets
+
+Run the assets generator to set up your own TailwindCSS build:
+
+```bash
+rails generate pu:core:assets
+```
+
+This:
+1. Installs required npm packages (`@radioactive-labs/plutonium`, TailwindCSS plugins)
+2. Creates `tailwind.config.js` that extends Plutonium's config
+3. Imports Plutonium CSS into your `application.tailwind.css`
+4. Registers Plutonium's Stimulus controllers
+5. Updates Plutonium config to use your assets
+
+## Asset Configuration
+
+Configure assets in the initializer:
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure do |config|
+  config.load_defaults 1.0
+
+  config.assets.stylesheet = "application"  # Your CSS file
+  config.assets.script = "application"      # Your JS file
+  config.assets.logo = "my_logo.png"        # Logo image
+  config.assets.favicon = "my_favicon.ico"  # Favicon
+end
+```
+
+## TailwindCSS Configuration
+
+### Generated Config
+
+```javascript
+// tailwind.config.js
+const { execSync } = require('child_process');
+const plutoniumGemPath = execSync("bundle show plutonium").toString().trim();
+const plutoniumTailwindConfig = require(`${plutoniumGemPath}/tailwind.options.js`)
+
+module.exports = {
+  darkMode: plutoniumTailwindConfig.darkMode,
+  plugins: [
+    // Add your plugins here
+  ].concat(plutoniumTailwindConfig.plugins),
+  theme: plutoniumTailwindConfig.merge(
+    plutoniumTailwindConfig.theme,
+    {
+      // Your custom theme overrides
+    },
+  ),
+  content: [
+    `${__dirname}/app/**/*.{erb,haml,html,slim,rb}`,
+    `${__dirname}/app/javascript/**/*.js`,
+    `${__dirname}/packages/**/app/**/*.{erb,haml,html,slim,rb}`,
+  ].concat(plutoniumTailwindConfig.content),
+}
+```
+
+### Customizing Colors
+
+Override Plutonium's color palette:
+
+```javascript
+// tailwind.config.js
+theme: plutoniumTailwindConfig.merge(
+  plutoniumTailwindConfig.theme,
+  {
+    extend: {
+      colors: {
+        primary: {
+          50: '#eff6ff',
+          100: '#dbeafe',
+          200: '#bfdbfe',
+          300: '#93c5fd',
+          400: '#60a5fa',
+          500: '#3b82f6',  // Your brand color
+          600: '#2563eb',
+          700: '#1d4ed8',
+          800: '#1e40af',
+          900: '#1e3a8a',
+          950: '#172554',
+        },
+      },
+    },
+  },
+),
+```
+
+### Semantic Colors
+
+Plutonium includes these semantic colors:
+
+| Color | Usage |
+|-------|-------|
+| `primary` | Primary brand color |
+| `secondary` | Secondary color |
+| `success` | Success states (green) |
+| `info` | Informational states (blue) |
+| `warning` | Warning states (amber) |
+| `danger` | Error/danger states (red) |
+| `accent` | Accent highlights |
+
+## CSS Imports
+
+### Application Stylesheet
+
+```css
+/* app/assets/stylesheets/application.tailwind.css */
+@import "gem:plutonium/src/css/plutonium.css";
+
+@import "tailwindcss";
+@config '../../../tailwind.config.js';
+
+/* Your custom styles */
+```
+
+## Component Themes
+
+Plutonium components use a theme system. Override themes by defining nested Theme classes in your definitions.
+
+### Form Theme
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Form < Form
+    class Theme < Plutonium::UI::Form::Theme
+      def self.theme
+        super.merge({
+          base: "bg-white dark:bg-gray-800 shadow-md rounded-lg p-6",
+          fields_wrapper: "grid grid-cols-2 gap-6",
+          actions_wrapper: "flex justify-end mt-6 space-x-2",
+          label: "block mb-2 text-base font-bold",
+          input: "w-full p-2 border rounded-md shadow-sm",
+          hint: "mt-2 text-sm text-gray-500",
+          error: "mt-2 text-sm text-red-600",
+          button: "px-4 py-2 bg-primary-600 text-white rounded-md hover:bg-primary-700",
+        })
+      end
+    end
+  end
+end
+```
+
+### Display Theme
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Display < Display
+    class Theme < Plutonium::UI::Display::Theme
+      def self.theme
+        super.merge({
+          fields_wrapper: "grid grid-cols-3 gap-8",
+          label: "text-sm font-bold text-gray-500 mb-1",
+          string: "text-lg text-gray-900 dark:text-white",
+          link: "text-primary-600 hover:underline",
+        })
+      end
+    end
+  end
+end
+```
+
+### Table Theme
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Table < Table
+    class Theme < Plutonium::UI::Table::Theme
+      def self.theme
+        super.merge({
+          wrapper: "overflow-x-auto shadow-md rounded-lg",
+          base: "w-full text-sm text-gray-500",
+          header: "text-xs uppercase bg-gray-100 dark:bg-gray-700",
+          header_cell: "px-6 py-3",
+          body_row: "bg-white border-b dark:bg-gray-800",
+          body_cell: "px-6 py-4",
+        })
+      end
+    end
+  end
+end
+```
+
+## Branding
+
+### Application Name
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.application_name = "My Application"
+```
+
+### Custom Logo
+
+Override the logo in your layout:
+
+```ruby
+# packages/admin_portal/app/views/layouts/admin_portal/application.rb
+module AdminPortal
+  class ApplicationLayout < Plutonium::UI::Layout::Application
+    def render_logo
+      img(src: helpers.asset_path("logo.svg"), alt: "My App", class: "h-8")
+    end
+  end
+end
+```
+
+### Custom Fonts
+
+Override in your layout:
+
+```ruby
+class MyLayout < Plutonium::UI::Layout::ResourceLayout
+  def render_fonts
+    link(rel: "preconnect", href: "https://fonts.googleapis.com")
+    link(href: "https://fonts.googleapis.com/css2?family=Inter&display=swap", rel: "stylesheet")
+  end
+end
+```
+
+Update Tailwind config:
+
+```javascript
+theme: {
+  fontFamily: {
+    'body': ['Inter', 'sans-serif'],
+    'sans': ['Inter', 'sans-serif'],
+  }
+}
+```
+
+## Dark Mode
+
+Plutonium uses `selector` strategy for dark mode. Toggle by adding/removing the `dark` class on `<html>`:
+
+```javascript
+document.documentElement.classList.toggle('dark');
+```
+
+Plutonium includes a color mode selector component that handles this automatically.
+
+## Stimulus Controllers
+
+Register Plutonium's Stimulus controllers in your application:
+
+```javascript
+// app/javascript/controllers/index.js
+import { application } from "./application"
+
+import { registerControllers } from "@radioactive-labs/plutonium"
+registerControllers(application)
+
+// Your custom controllers...
+```
+
+### Available Controllers
+
+- `color-mode` - Dark/light mode toggle
+- `form` - Form handling
+- `nested-resource-form-fields` - Nested form management
+- `slim-select` - Enhanced select boxes
+- `flatpickr` - Date/time pickers
+- `easymde` - Markdown editor
+
+### Custom Controllers
+
+```javascript
+// app/javascript/controllers/custom_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  connect() {
+    console.log("Connected")
+  }
+}
+```
+
+Register in your index:
+
+```javascript
+import CustomController from "./custom_controller"
+application.register("custom", CustomController)
+```
+
+## Portal-Specific Themes
+
+Different portals can have different themes by overriding definitions per-portal:
+
+```ruby
+# packages/admin_portal/app/definitions/admin_portal/post_definition.rb
+class AdminPortal::PostDefinition < ::PostDefinition
+  class Form < Form
+    class Theme < Plutonium::UI::Form::Theme
+      def self.theme
+        super.merge({
+          base: "bg-blue-50 p-8",  # Admin-specific styling
+        })
+      end
+    end
+  end
+end
+```
+
+## Related
+
+- [Custom Actions](./custom-actions)
+- [Creating Packages](./creating-packages)

data/docs/index.md

@@ -1,40 +1,81 @@
 ---
-# https://vitepress.dev/reference/default-theme-home-page
 layout: home
-
 hero:
   name: Plutonium
-  text: The Rails RAD Toolkit
-  tagline: Build feature-rich, enterprise-ready applications at lightning speed. Stop writing boilerplate, start building features.
-  image:
-    src: /plutonium.png
-    alt: Plutonium
+  text: Rapid Application Development for Rails
+  tagline: Build production-ready Rails applications in minutes, not months. Convention-driven, fully customizable.
   actions:
     - theme: brand
-      text: Start the Tutorial
-      link: /guide/tutorial/01-project-setup
+      text: Get Started
+      link: /getting-started/
     - theme: alt
-      text: Core Concepts
-      link: /guide/introduction/02-core-concepts
+      text: View on GitHub
+      link: https://github.com/radioactive-labs/plutonium-core
 
 features:
   - icon: 🚀
-    title: Unmatched Developer Experience
-    details: Smart generators, convention-over-configuration, and intelligent defaults let you focus on what matters.
-  - icon: 🏗️
-    title: Robust Architecture
-    details: Built-in multitenancy, modular packages, and advanced authorization provide a solid foundation for any project.
+    title: Zero to Production Fast
+    details: Generate complete CRUD interfaces with a single command. Authentication, authorization, and UI included out of the box.
+  - icon: 🧩
+    title: Modular Architecture
+    details: Organize your app into Feature Packages and Portals. Each module is isolated, testable, and reusable.
   - icon: 🎨
-    title: Flexible UI & Theming
-    details: Start with a beautiful, modern UI out-of-the-box, then customize any aspect with a powerful and expressive API.
-
+    title: Fully Customizable
+    details: Every layer is overridable. Customize fields, forms, tables, pages, and styles without fighting the framework.
+  - icon: 🔐
+    title: Built-in Authorization
+    details: Policy-based authorization at every level - actions, attributes, and collection scoping. Multi-tenancy ready.
+  - icon: 📦
+    title: Convention over Configuration
+    details: Smart defaults detect your models, associations, and validations. Only configure what you need to change.
+  - icon: 🛠️
+    title: Rails Native
+    details: Built on Rails conventions. Uses Phlex for views, Rodauth for auth, and standard Rails patterns throughout.
 ---
 
-<style>
-:root {
-  --vp-home-hero-name-color: transparent;
-  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #da8ee7 30%, #5f4dff);
+## Why Plutonium?
+
+Building admin panels, dashboards, and internal tools in Rails often means:
+- Writing repetitive CRUD code
+- Building authorization from scratch
+- Creating forms and tables manually
+- Handling multi-tenancy yourself
+
+**Plutonium eliminates this boilerplate** while remaining fully customizable.
+
+```bash
+# Create a new Plutonium app
+rails new myapp -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+
+# Generate a resource
+rails g pu:res:scaffold Post title:string body:text published:boolean
+
+# Connect it to a portal
+rails g pu:res:conn Post --portal AdminPortal
+
+# Done. Full CRUD with auth, policies, and UI.
+```
+
+## How It Works
+
+Plutonium follows a layered architecture where each layer has a single responsibility:
+
+| Layer | Purpose | File |
+|-------|---------|------|
+| **Model** | Data structure and validations | `app/models/post.rb` |
+| **Definition** | How the resource renders (fields, actions) | `app/definitions/post_definition.rb` |
+| **Policy** | Who can do what | `app/policies/post_policy.rb` |
+| **Controller** | HTTP handling and customization | `app/controllers/posts_controller.rb` |
+
+Each layer auto-detects sensible defaults. You only write code when you need to customize.
+
+## Quick Links
+
+<div class="quick-links">
+
+- [Installation Guide](/getting-started/installation) - Set up Plutonium in a new or existing Rails app
+- [Tutorial](/getting-started/tutorial/) - Build a complete blog application step by step
+- [Architecture Overview](/concepts/architecture) - Understand how the pieces fit together
+- [Reference Documentation](/reference/model/) - Detailed API documentation
 
-  --vp-home-hero-image-filter: blur(56px);
-}
-</style>
+</div>