plutonium 0.33.1 → 0.34.0

data/docs/public/CLAUDE.md

@@ -20,11 +20,13 @@ rails generate pu:rodauth:account user
 rails generate pu:pkg:package blog_management
 rails generate pu:pkg:portal admin_portal
 
-# Create complete resource
+# Create complete resource (always specify --dest to avoid prompts)
 rails generate pu:res:scaffold Post user:belongs_to title:string content:text --dest=blog_management
+rails generate pu:res:scaffold User name:string email:string:uniq --dest=main_app  # main app resource
 
 # Connect to portal
 rails generate pu:res:conn BlogManagement::Post --dest=admin_portal
+rails generate pu:res:conn User --dest=admin_portal  # main app resource (no namespace)
 ```
 
 ### Start Building
@@ -43,7 +45,7 @@ bin/dev  # Visit http://localhost:3000
 - **Entity Scoping**: Built-in multi-tenancy support
 
 ### 2. Key Components
-- **Models**: ActiveRecord + `Plutonium::Resource::Record` for enhanced functionality
+- **Models**: ActiveRecord with `ResourceRecord` base class for enhanced functionality
 - **Definitions**: Declarative UI configuration (how fields render)
 - **Policies**: Authorization control (what users can access)
 - **Interactions**: Business logic encapsulation (what actions do)
@@ -123,26 +125,32 @@ rails generate pu:pkg:portal admin_dashboard
 ```
 
 ### Resource Generators (Most Important)
+
+**Always specify `--dest`** to avoid interactive prompts:
+
 ```bash
-# Complete resource scaffold (preferred) - use --dest for package
+# Main app resource (not in a package)
+rails generate pu:res:scaffold Post user:belongs_to title:string 'content:text?' --dest=main_app
+
+# Package resource
 rails generate pu:res:scaffold Post user:belongs_to title:string content:text 'published_at:datetime?' --dest=blogging
 
 # Referencing namespaced models in associations
 rails generate pu:res:scaffold Comment user:belongs_to blogging/post:belongs_to body:text --dest=comments
 rails generate pu:res:scaffold Order customer:belongs_to inventory/product:belongs_to quantity:integer --dest=commerce
 
-# Model only - use --dest for package
+# Model only
 rails generate pu:res:model Article title:string body:text author:belongs_to --dest=blogging
 rails generate pu:res:model Review user:belongs_to inventory/product:belongs_to rating:integer --dest=reviews
 
 # CRITICAL: Use connection generator to expose resources in portals
 # Always use the generator - NEVER manually connect resources
 
-# Use full namespaced path (package_name/model_name format)
-rails generate pu:res:conn blog_management/post blog_management/comment --dest=admin_portal
+# Use full class name for namespaced resources
+rails generate pu:res:conn BlogManagement::Post BlogManagement::Comment --dest=admin_portal
 
-# Interactive mode (will prompt for resource and portal selection)
-rails generate pu:res:conn
+# Main app resources (not namespaced)
+rails generate pu:res:conn Post Comment --dest=admin_portal
 
 # The generator handles all routing, controller, and policy connections automatically
 ```
@@ -406,17 +414,49 @@ end
 ### Database Setup
 - Use standard Rails migration conventions
 - Always inline indexes and constraints in create_table blocks
-- Use nullable fields with `'field:type?'` syntax
-- Reference namespaced models: `package_name/model:belongs_to`
 - Leverage Rails associations (`belongs_to`, `has_many`, etc.)
 
-### Cross-Package Associations
+### Generator Field Syntax
+
+**IMPORTANT**: Quote fields containing `?` or `{}` to prevent shell expansion.
+
+**IMPORTANT**: Always specify `--dest` to avoid interactive prompts:
+- `--dest=main_app` for resources in the main application
+- `--dest=package_name` for resources in a feature package
+
 ```bash
-# When generating models that reference other packages
-rails generate pu:res:scaffold Comment user:belongs_to blogging/post:belongs_to body:text --dest=comments
+# Nullable fields
+'name:string?'                    # null: true
+'parent:belongs_to?'              # null: true + optional: true in model
 
-# This creates the correct association:
+# Decimal precision (only works for decimal type)
+'price:decimal{10,2}'             # precision: 10, scale: 2
+'amount:decimal?{10,2}'           # nullable with precision
+
+# For default values on other types (boolean, integer, etc.),
+# edit the migration manually after generation
+
+# Indexes
+email:string:index                # Regular index
+email:string:uniq                 # Unique index
+
+# Cross-package references
+blogging/post:belongs_to          # belongs_to :post, class_name: "Blogging::Post"
+```
+
+### Cross-Package Associations
+```bash
+# Reference models from other packages using package/model syntax
+rails generate pu:res:scaffold Comment \
+    user:belongs_to \
+    blogging/post:belongs_to \
+    'parent:belongs_to?' \
+    body:text \
+    --dest=comments
+
+# Generates:
 # belongs_to :post, class_name: "Blogging::Post"
+# belongs_to :parent, optional: true
 ```
 
 ### Entity Scoping (Multi-Tenancy) Setup
@@ -426,13 +466,15 @@ Plutonium provides powerful multi-tenancy through Entity Scoping, which automati
 #### 1. Configure Portal Engine
 ```ruby
 # In packages/admin_portal/lib/engine.rb
-scope_to_entity Organization, strategy: :path  # URLs: /organizations/:organization_id/posts
+config.after_initialize do
+  scope_to_entity Organization, strategy: :path  # URLs: /organizations/:organization_id/posts
 
-# Custom strategy (subdomain-based)
-scope_to_entity Organization, strategy: :current_organization  # URLs: /posts on acme.app.com
+  # Custom strategy (subdomain-based)
+  scope_to_entity Organization, strategy: :current_organization  # URLs: /posts on acme.app.com
 
-# Custom parameter name
-scope_to_entity Client, strategy: :path, param_key: :client_slug  # URLs: /clients/:client_slug/posts
+  # Custom parameter name
+  scope_to_entity Client, strategy: :path, param_key: :client_slug  # URLs: /clients/:client_slug/posts
+end
 ```
 
 #### 2. Implement Custom Strategy Methods
@@ -502,9 +544,10 @@ end
 ## Quick Reference Commands
 
 ```bash
-# Essential workflow
+# Essential workflow (always use --dest to avoid prompts)
 rails generate pu:pkg:package feature_name                    # Create feature package
-rails generate pu:res:scaffold Resource --dest=feature_name   # Create complete resource
+rails generate pu:res:scaffold Resource --dest=main_app       # Main app resource
+rails generate pu:res:scaffold Resource --dest=feature_name   # Package resource
 rails generate pu:pkg:portal portal_name                      # Create portal
 rails generate pu:res:conn Feature::Resource --dest=portal    # CRITICAL: Always use generator to connect
 

data/docs/reference/assets/index.md

@@ -0,0 +1,496 @@
+# Assets Reference
+
+Complete reference for styling, theming, and frontend assets.
+
+## Overview
+
+Plutonium uses:
+- **TailwindCSS** for styling
+- **Stimulus** for JavaScript interactions
+- **Turbo** for navigation and forms
+
+## 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
+
+  # Custom assets
+  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),
+}
+```
+
+### CSS Imports
+
+```css
+/* app/assets/stylesheets/application.tailwind.css */
+@import "gem:plutonium/src/css/plutonium.css";
+
+@import "tailwindcss";
+@config '../../../tailwind.config.js';
+
+/* Your custom styles */
+```
+
+### What Plutonium CSS Includes
+
+- Core utility classes
+- EasyMDE (markdown editor) styles
+- Slim Select styles
+- International telephone input styles
+- Flatpickr (date picker) styles
+
+## Color System
+
+### Customizing Colors
+
+Override Plutonium's color palette in your Tailwind config:
+
+```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',
+        },
+      },
+    },
+  },
+),
+```
+
+### Default Color Palette
+
+Plutonium includes these semantic colors:
+
+| Color | Usage |
+|-------|-------|
+| `primary` | Primary brand color (turquoise by default) |
+| `secondary` | Secondary color (navy by default) |
+| `success` | Success states (green) |
+| `info` | Informational states (blue) |
+| `warning` | Warning states (amber) |
+| `danger` | Error/danger states (red) |
+| `accent` | Accent highlights (coral pink) |
+
+## Dark Mode
+
+Plutonium uses `selector` strategy for dark mode:
+
+```javascript
+darkMode: "selector"
+```
+
+Toggle dark mode by adding/removing the `dark` class on `<html>`:
+
+```javascript
+document.documentElement.classList.toggle('dark');
+```
+
+Plutonium includes a `color-mode` Stimulus controller that handles this automatically.
+
+## Component Themes
+
+Plutonium components use a theme system based on Phlexi. Each component type has a theme class with named style tokens.
+
+### Form Theme
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Form < Form
+    class Theme < Plutonium::UI::Form::Theme
+      def self.theme
+        super.merge({
+          # Container
+          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",
+
+          # Labels
+          label: "block mb-2 text-base font-bold",
+          invalid_label: "text-red-700 dark:text-red-500",
+          valid_label: "text-green-700 dark:text-green-500",
+          neutral_label: "text-gray-500 dark:text-gray-400",
+
+          # Inputs
+          input: "w-full p-2 border rounded-md shadow-sm",
+          invalid_input: "bg-red-50 border-red-500 text-red-900",
+          valid_input: "bg-green-50 border-green-500 text-green-900",
+          neutral_input: "border-gray-300 dark:border-gray-600",
+
+          # Hints & Errors
+          hint: "mt-2 text-sm text-gray-500",
+          error: "mt-2 text-sm text-red-600",
+
+          # Buttons
+          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",
+          markdown: "prose dark:prose-invert max-w-none",
+        })
+      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
+```
+
+### Theme Keys Reference
+
+#### Form Theme Keys
+
+| Key | Description |
+|-----|-------------|
+| `base` | Form container |
+| `fields_wrapper` | Grid wrapper for fields |
+| `actions_wrapper` | Submit button container |
+| `wrapper` | Individual field wrapper |
+| `inner_wrapper` | Inner field wrapper |
+| `label` | Label base styles |
+| `invalid_label` | Label when field invalid |
+| `valid_label` | Label when field valid |
+| `neutral_label` | Label default state |
+| `input` | Input base styles |
+| `invalid_input` | Input when invalid |
+| `valid_input` | Input when valid |
+| `neutral_input` | Input default state |
+| `hint` | Hint text |
+| `error` | Error message |
+| `button` | Submit button |
+| `checkbox` | Checkbox input |
+| `select` | Select dropdown |
+
+#### Display Theme Keys
+
+| Key | Description |
+|-----|-------------|
+| `fields_wrapper` | Grid wrapper |
+| `label` | Field label |
+| `description` | Field description |
+| `string` | String values |
+| `text` | Text values |
+| `link` | URL links |
+| `email` | Email links |
+| `phone` | Phone links |
+| `markdown` | Markdown content |
+| `json` | JSON display |
+
+#### Table Theme Keys
+
+| Key | Description |
+|-----|-------------|
+| `wrapper` | Table container |
+| `base` | Table element |
+| `header` | Header row |
+| `header_cell` | Header cell |
+| `body_row` | Body row |
+| `body_cell` | Body cell |
+| `sort_icon` | Sort indicator |
+
+## Using Tokens in Components
+
+### The `tokens` Helper
+
+Conditionally apply classes:
+
+```ruby
+class MyComponent < Plutonium::UI::Component::Base
+  def initialize(active:)
+    @active = active
+  end
+
+  def view_template
+    div(class: tokens(
+      "base-class",
+      active?: "bg-primary-500 text-white",
+      inactive?: "bg-gray-200 text-gray-700"
+    )) {
+      "Content"
+    }
+  end
+
+  private
+
+  def active? = @active
+  def inactive? = !@active
+end
+```
+
+### The `classes` Helper
+
+Returns a hash suitable for splatting:
+
+```ruby
+div(**classes("p-4", "rounded", active?: "ring-2")) { }
+# => <div class="p-4 rounded ring-2">
+```
+
+### Conditional Tokens with Then/Else
+
+For if/else class logic, pass a hash with `:then` and `:else` keys:
+
+```ruby
+class MyComponent < Plutonium::UI::Component::Base
+  def initialize(status:)
+    @status = status
+  end
+
+  def view_template
+    div(class: tokens(
+      "badge",
+      published?: { then: "bg-green-500", else: "bg-gray-500" }
+    )) { @status }
+  end
+
+  private
+
+  def published? = @status == "published"
+end
+```
+
+## Stimulus Controllers
+
+Plutonium includes Stimulus controllers. Register them in your application:
+
+```javascript
+// app/javascript/controllers/index.js
+import { application } from "./application"
+
+import { registerControllers } from "@radioactive-labs/plutonium"
+registerControllers(application)
+
+// Your custom controllers...
+```
+
+### Built-in Controllers
+
+See the [register_controllers.js source](https://github.com/radioactive-labs/plutonium-core/blob/master/src/js/controllers/register_controllers.js) for the current list of controllers.
+
+Key controllers include:
+
+| Controller | Purpose |
+|------------|---------|
+| `form` | Form handling (pre-submit, etc.) |
+| `nested-resource-form-fields` | Nested form management |
+| `slim-select` | Enhanced select boxes |
+| `flatpickr` | Date/time pickers |
+| `easymde` | Markdown editor |
+| `color-mode` | Dark/light mode toggle |
+| `sidebar` | Sidebar navigation |
+| `remote-modal` | Remote modal dialogs |
+| `intl-tel-input` | International phone input |
+| `attachment-input` | File attachment handling |
+
+### Custom Controllers
+
+Add your own controllers alongside Plutonium's:
+
+```javascript
+// app/javascript/controllers/custom_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  connect() {
+    console.log("Custom controller connected")
+  }
+}
+```
+
+Register in your index:
+
+```javascript
+import CustomController from "./custom_controller"
+application.register("custom", CustomController)
+```
+
+## Icons
+
+Plutonium uses Tabler Icons via Phlex:
+
+```ruby
+# In views
+render Phlex::TablerIcons::Home.new(class: "w-5 h-5")
+render Phlex::TablerIcons::User.new(class: "w-5 h-5 text-gray-500")
+```
+
+### Icon Sizes
+
+```ruby
+Phlex::TablerIcons::Home.new(class: "w-4 h-4")  # Small
+Phlex::TablerIcons::Home.new(class: "w-5 h-5")  # Default
+Phlex::TablerIcons::Home.new(class: "w-6 h-6")  # Large
+```
+
+## Typography
+
+Plutonium uses Lato font by default. The layout loads it from Google Fonts.
+
+Override in your layout:
+
+```ruby
+class MyLayout < Plutonium::UI::Layout::ResourceLayout
+  def render_fonts
+    # Your custom 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'],
+  }
+}
+```
+
+## Custom Styles
+
+### Adding Custom Utilities
+
+```css
+@layer utilities {
+  .text-gradient {
+    background: linear-gradient(to right, var(--tw-gradient-from), var(--tw-gradient-to));
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+  }
+
+  .animate-fade-in {
+    animation: fadeIn 0.3s ease-in-out;
+  }
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+```
+
+### Component Classes
+
+```css
+@layer components {
+  .btn {
+    @apply px-4 py-2 rounded font-medium transition-colors;
+  }
+
+  .btn-primary {
+    @apply bg-primary-600 text-white hover:bg-primary-700;
+  }
+
+  .card {
+    @apply bg-white rounded-lg shadow p-6;
+  }
+}
+```
+
+## Related
+
+- [Theming Guide](/guides/theming)
+- [Views Reference](/reference/views/)
+- [Forms Reference](/reference/views/forms)