plutonium 0.34.1 → 0.35.0

data/CHANGELOG.md

@@ -1,3 +1,55 @@
+## [0.35.0] - 2026-01-20
+
+### 🚀 Features
+
+- Add demo_features package and demo_portal for testing
+- Implement bulk actions for resource tables
+- Modernize UI with design token system and component classes
+- Add actions dropdown for secondary and danger actions
+- Add form input type aliases for explicit field type declarations
+- Add built-in filter types with dropdown filter panel UI
+- *(display)* Add boolean and color components with type aliases
+- *(filters)* Add clear all button with filter-panel controller
+
+### 🐛 Bug Fixes
+
+- Use turbo stream redirect action instead of HTTP 302 for form submissions
+- Exclude turbo_stream format from URL preservation
+- Improve table container scroll and telephone input padding
+- Pass unwrapped record into custom column blocks
+- *(docs)* Prevent h2 text cutoff in VitePress docs
+
+### 🚜 Refactor
+
+- Remove ResourceController from portal generator
+- Rename skills with plutonium- prefix to avoid conflicts
+- Simplify dashboard templates with design system classes
+- *(ui)* Update auth pages with new design tokens
+
+### 📚 Documentation
+
+- Improve interaction docs
+- Overhaul README, CONTRIBUTING, and add CLAUDE.md for development
+- Redesign landing page with modern layout and AI messaging
+- Unify branding and add social preview meta tags
+- Fix broken links
+- Add Author Portal tutorial chapter
+- Fix minimum rails version
+- Fix drafts scope for posts
+- Remove cookbooks
+- Reorganize features section of homepage
+- Clean up docs and fix misc issues
+- Rewrite theming guide with design tokens and component classes
+- Removed potentially misleading section on per portal themes
+- Document authorization methods
+- Add skills for themeing specifically
+
+### ⚙️ Miscellaneous Tasks
+
+- Optimize og graph title and images
+- Realign marketing material
+- Add seeds for demo models and fix foreign keys
+- Standardrb
 ## [0.34.1] - 2026-01-18
 
 ### 🐛 Bug Fixes

data/CLAUDE.md

@@ -0,0 +1,215 @@
+# Plutonium Core Development Guide
+
+This guide helps AI assistants contribute to the Plutonium framework itself.
+
+## Project Overview
+
+Plutonium is a Rails RAD framework distributed as a Ruby gem. It provides resource-oriented architecture with automatic CRUD, policies, definitions, and multi-tenancy.
+
+## Repository Structure
+
+```
+plutonium-core/
+├── lib/plutonium/              # Core framework code
+│   ├── resource/               # Resource system (controllers, policies, definitions)
+│   ├── portal/                 # Portal engines and multi-tenancy
+│   ├── interaction/            # Business logic encapsulation
+│   ├── ui/                     # Phlex view components
+│   ├── definition/             # Definition DSL and field types
+│   ├── query/                  # Search, filters, scopes
+│   ├── auth/                   # Authentication (Rodauth integration)
+│   ├── routing/                # Route helpers and extensions
+│   └── generators/             # Rails generators (pu:res:scaffold, etc.)
+├── app/                        # Rails app components
+│   ├── assets/                 # JavaScript, CSS
+│   ├── controllers/            # Base controllers
+│   └── views/                  # Phlex components
+├── test/                       # Test suite
+│   ├── plutonium/              # Unit tests mirroring lib/ structure
+│   ├── dummy/                  # Test Rails app
+│   └── system/                 # System/integration tests
+├── docs/                       # VitePress documentation site
+│   ├── getting-started/
+│   ├── guides/
+│   └── reference/
+└── .claude/skills/             # AI assistant skills (documentation for Claude)
+```
+
+## Key Abstractions
+
+### Resource System
+- `Plutonium::Resource::Record` - Model mixin with `associated_with` scopes
+- `Plutonium::Resource::Policy` - ActionPolicy-based authorization
+- `Plutonium::Resource::Definition` - Declarative UI configuration
+- `Plutonium::Resource::Controller` - CRUD controller mixin
+- `Plutonium::Resource::Interaction` - Business logic encapsulation
+
+### Portal System
+- `Plutonium::Portal::Engine` - Rails engine mixin for web interfaces
+- `Plutonium::Package::Engine` - Rails engine mixin for feature packages
+- Entity scoping for multi-tenancy (path or custom strategy)
+
+### UI Components
+Located in `lib/plutonium/ui/` - Phlex-based components:
+- `page/` - Page layouts (index, show, new, edit)
+- `form/` - Form builders and field components
+- `table/` - Data tables with sorting, pagination
+- `display/` - Field display components
+
+## Development Workflow
+
+### Environment Setup
+
+When working on Plutonium itself, set:
+
+```bash
+export PLUTONIUM_DEV=1
+```
+
+This enables development mode which:
+- Uses local assets instead of packaged ones
+- Enables hot reloading of components
+- Shows more detailed error messages
+
+### Building Assets
+
+When working on JavaScript or CSS in `src/`:
+
+```bash
+# Watch mode (rebuilds on changes to src/build/)
+npm run dev
+
+# Production build (to app/assets/)
+npm run build
+```
+
+- `npm run dev` - watches and rebuilds to `src/build/` for development
+- `npm run build` - compiles to `app/assets/` for release
+
+**Always run `npm run dev`** in a terminal when working on frontend code.
+
+### Running Tests
+
+Tests use [Appraisal](https://github.com/thoughtbot/appraisal) for multiple Rails versions:
+
+```bash
+# Full test suite (all Rails versions)
+bundle exec appraisal rake test
+
+# Specific Rails version
+bundle exec appraisal rails-8.1 rake test
+
+# Specific test file
+bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/resource/policy_test.rb
+```
+
+Available: `rails-7`, `rails-8.0`, `rails-8.1`
+
+### Testing Generators
+
+Generators are in `lib/generators/pu/`. Test by:
+1. Running in the dummy app: `cd test/dummy && rails g pu:res:scaffold ...`
+2. Generator tests in `test/generators/`
+
+### Documentation
+
+```bash
+cd docs
+pnpm install
+pnpm dev          # Local preview at localhost:5173
+pnpm build        # Build for production
+```
+
+## Code Conventions
+
+### Ruby Style
+- Follow Rails conventions
+- Use `with_connection` for database operations (fiber-safe)
+- Avoid excessive defensive programming (no `respond_to?` checks)
+- Use `Rails.logger.warn { "message" }` block syntax in production code
+
+### Generators
+- Always provide `--dest=` flag support to avoid interactive prompts
+- Use `--dest=main_app` for main application, `--dest=package_name` for packages
+- Quote shell arguments with special characters: `'field:type?'`, `'field:decimal{10,2}'`
+
+### Migrations
+- Inline indexes and constraints in `create_table` blocks
+- Use `foreign_key: {on_delete: :cascade}` where appropriate
+
+### Frontend
+- Stimulus controllers for interactivity (always register controllers)
+- TailwindCSS 4 for styling
+- Phlex for view components
+
+## Adding New Features
+
+### New Field Type
+1. Add renderer in `lib/plutonium/ui/display/components/`
+2. Add input in `lib/plutonium/ui/form/components/`
+3. Register in field type mappings
+4. Add tests and documentation
+
+### New Generator
+1. Create in `lib/generators/pu/category/name_generator.rb`
+2. Add templates in `lib/generators/pu/category/name/templates/`
+3. Add tests in `test/generators/`
+4. Document in `docs/reference/generators/`
+
+### New Interaction Response
+1. Add response class in `lib/plutonium/interaction/response/`
+2. Add helper method in `Plutonium::Interaction::Outcome::Success`
+3. Document usage
+
+## Skills System
+
+The `.claude/skills/` directory contains documentation for AI assistants:
+- Each skill is a focused guide on one concept
+- Skills are loaded based on user queries
+- Update skills when changing related functionality
+- Skills require a gem release to take effect
+
+## Release Process
+
+```bash
+bundle exec rake release:full
+```
+
+This:
+1. Checks npm authentication
+2. Bumps version
+3. Builds and publishes npm package
+4. Builds and publishes gem
+5. Pushes git tags
+
+## Key Files Reference
+
+| Purpose | Location |
+|---------|----------|
+| Gem version | `lib/plutonium/version.rb` |
+| Main entry | `lib/plutonium.rb` |
+| Configuration | `lib/plutonium/configuration.rb` |
+| Base controller | `lib/plutonium/resource/controller.rb` |
+| Base policy | `lib/plutonium/resource/policy.rb` |
+| Base definition | `lib/plutonium/resource/definition.rb` |
+| Interactions | `lib/plutonium/interaction/base.rb` |
+| Generators | `lib/generators/pu/` |
+
+## Common Tasks
+
+### Fix a bug in policies
+1. Find the issue in `lib/plutonium/resource/policy.rb` or related
+2. Write a failing test in `test/plutonium/resource/policy_test.rb`
+3. Fix the bug
+4. Update docs if behavior changed
+
+### Add a generator option
+1. Add option in generator class
+2. Update templates to use option
+3. Test with dummy app
+4. Document in `docs/reference/generators/`
+
+### Update documentation
+1. Edit files in `docs/`
+2. If user-facing behavior, update relevant skill in `.claude/skills/`
+3. Run `pnpm build` to verify no broken links

data/CONTRIBUTING.md

@@ -92,29 +92,83 @@ git push origin main --tags
 # 4. GitHub Actions will automatically publish to RubyGems
 ```
 
-## Version Bumping Rules
-
-Following semantic versioning:
+## Development Setup
 
-- **MAJOR** (X.0.0): Breaking changes
-- **MINOR** (0.X.0): New features (backwards compatible)
-- **PATCH** (0.0.X): Bug fixes (backwards compatible)
+### Prerequisites
 
-The automation determines the version bump based on commits since the last tag:
-- Any commit with `BREAKING CHANGE:` or `!` after type → MAJOR
-- Any `feat:` commits → MINOR
-- Any `fix:` commits → PATCH
+- Ruby 3.2+
+- Node.js 18+
+- PostgreSQL (for tests)
 
-## Development Setup
+### Install Dependencies
 
 ```bash
-# Install dependencies
 bundle install
+npm install
+```
+
+### Environment
+
+Set this when working on Plutonium:
+
+```bash
+export PLUTONIUM_DEV=1
+```
+
+This uses local assets and enables hot reloading.
+
+### Building Assets
+
+Frontend source is in `src/`. When making JS or CSS changes:
+
+```bash
+# Watch mode - keeps rebuilding as you edit
+npm run dev
+
+# Production build - run before committing
+npm run build
+```
+
+### Running Tests
 
-# Run tests
-bundle exec rspec
+Tests run via [Appraisal](https://github.com/thoughtbot/appraisal) against multiple Rails versions:
 
-# Install git-cliff for changelog generation (optional)
+```bash
+# Full test suite (all Rails versions)
+bundle exec appraisal rake test
+
+# Specific Rails version
+bundle exec appraisal rails-8.1 rake test
+
+# Specific test file
+bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/resource/policy_test.rb
+```
+
+Available appraisals: `rails-7`, `rails-8.0`, `rails-8.1`
+
+### Testing Generators
+
+Use the dummy app:
+
+```bash
+cd test/dummy
+rails g pu:res:scaffold TestModel name:string --dest=main_app
+rails db:migrate
+bin/dev
+```
+
+### Documentation
+
+```bash
+cd docs
+pnpm install
+pnpm dev          # Preview at localhost:5173
+pnpm build        # Check for errors
+```
+
+### Changelog Generation (optional)
+
+```bash
 brew install git-cliff  # macOS
 # or
 cargo install git-cliff  # via Rust
@@ -125,9 +179,9 @@ cargo install git-cliff  # via Rust
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feat/my-feature`
 3. Make your changes with conventional commits
-4. Run tests: `bundle exec rspec`
-5. Push and create a pull request
-6. The PR title should also follow conventional commit format
+4. Run tests: `bundle exec appraisal rake test`
+5. Build assets: `npm run build`
+6. Push and create a pull request
 
 ## Questions?
 

data/README.md

@@ -1,33 +1,114 @@
-# Plutonium: It's like Rails, but for Rails!
+# Plutonium
 
+[![Gem Version](https://badge.fury.io/rb/plutonium.svg)](https://badge.fury.io/rb/plutonium)
 [![Ruby](https://github.com/radioactive-labs/plutonium-core/actions/workflows/main.yml/badge.svg)](https://github.com/radioactive-labs/plutonium-core/actions/workflows/main.yml)
 
-**Plutonium** is a powerful Rapid Application Development (RAD) toolkit for Rails that picks up where Rails left off, introducing application-level concepts and tooling that transform the way you build applications.
+Build production-ready Rails apps in minutes, not days. Convention-driven, fully customizable, and AI-ready. Plutonium picks up where Rails left off, adding application-level concepts that make building complex apps faster.
 
-## Overview
+## Quick Start
 
-Plutonium builds upon Rails' conventions and extends them with:
+```bash
+rails new myapp -a propshaft -j esbuild -c tailwind \
+  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+```
 
-- **Authentication & Authorization**: Integrates seamlessly with Rodauth or your existing auth system
-- **Complete CRUD Operations**: Rich fields, forms, tables, and nested resources out of the box
-- **Modular Architecture**: Package system based on Rails engines for better organization
-- **Entity Scoping**: Built-in multi-tenancy support that "just works"
-- **Smart Generators**: Eliminate boilerplate while maintaining flexibility
-- **Modern UI**: Beautiful, responsive interface powered by Tailwind CSS and Hotwire
+Then create your first resource:
 
-## Project Status
+```bash
+cd myapp
+rails g pu:res:scaffold Post title:string body:text --dest=main_app
+rails db:migrate
+bin/dev
+```
 
-> [!WARNING]
-> While Plutonium is actively used in production environments, it's still in early development. APIs may change, and some features are still evolving. We recommend thoroughly testing before deploying to production.
+Visit `http://localhost:3000` - you have a complete CRUD interface.
+
+## What You Get
+
+**Resource-oriented architecture** - Models, policies, definitions, and controllers that work together:
+
+```ruby
+# Policy controls WHO can do WHAT
+class PostPolicy < ResourcePolicy
+  def create? = user.present?
+  def update? = record.author == user || user.admin?
+
+  def permitted_attributes_for_create
+    %i[title body]
+  end
+end
+
+# Definition controls HOW it renders
+class PostDefinition < ResourceDefinition
+  input :body, as: :markdown
+  search { |scope, q| scope.where("title ILIKE ?", "%#{q}%") }
+  scope :published
+  scope :drafts
+end
+```
+
+**Packages for organization** - Split your app into feature packages and portals:
+
+```bash
+rails g pu:pkg:package blogging      # Business logic
+rails g pu:pkg:portal admin          # Web interface
+rails g pu:res:conn Post --dest=admin_portal
+```
+
+**Built-in authentication** via Rodauth:
+
+```bash
+rails g pu:rodauth:install
+rails g pu:rodauth:account user
+```
+
+**Multi-tenancy** with entity scoping:
+
+```ruby
+# In portal engine
+scope_to_entity Organization, strategy: :path
+# Routes become /organizations/:organization_id/posts
+```
+
+**Custom actions** with interactions:
+
+```ruby
+class PublishInteraction < ResourceInteraction
+  attribute :resource
+  attribute :publish_at, :datetime
+
+  def execute
+    resource.update!(published_at: publish_at)
+    succeed(resource).with_message("Published!")
+  rescue ActiveRecord::RecordInvalid => e
+    failed(e.record.errors)
+  end
+end
+```
 
 ## Documentation
 
-Visit our [documentation](https://radioactive-labs.github.io/plutonium-core/) for:
-- Getting started guide
-- Installation instructions
-- Core concepts
-- Tutorials
+Full documentation at **[radioactive-labs.github.io/plutonium-core](https://radioactive-labs.github.io/plutonium-core/)**
+
+- [Installation](https://radioactive-labs.github.io/plutonium-core/getting-started/installation)
+- [Tutorial](https://radioactive-labs.github.io/plutonium-core/getting-started/tutorial/)
+- [Guides](https://radioactive-labs.github.io/plutonium-core/guides/)
+- [Reference](https://radioactive-labs.github.io/plutonium-core/reference/)
+
+## Requirements
+
+- Ruby 3.2+
+- Rails 7.1+ (Rails 8 recommended)
+- Node.js 18+
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## Status
+
+Plutonium is used in production but still evolving. APIs may change between minor versions. Pin your version in Gemfile.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT License - see [LICENSE](LICENSE).