plutonium 0.50.0 → 0.51.0

data/.claude/skills/plutonium-views/SKILL.md

@@ -1,651 +0,0 @@
----
-name: plutonium-views
-description: Use BEFORE building a custom page, panel, table, layout, or Phlex component in Plutonium. Also when overriding IndexPage/ShowPage/Form classes in a definition.
----
-
-# Plutonium Views
-
-## 🚨 Critical (read first)
-- **Override via nested classes in the definition.** `class ShowPage < ShowPage; end`, `class Form < Form; end` — don't replace the entire view layer.
-- **Use the render hooks.** `render_before_content`, `render_after_content`, `render_before_toolbar`, etc. — they exist so you don't have to override `view_template` and re-implement everything.
-- **All pages inherit `DynaFrameContent`** so turbo-frame requests render only the content. Don't fight it — modals and frame nav "just work".
-- **For custom components, use `Plutonium::UI::Component::Base`** so you inherit the component kit (`PageHeader`, `Panel`, `Block`, etc.) and access to resource helpers.
-- **Related skills:** `plutonium-forms` (form customization), `plutonium-assets` (theming + component classes), `plutonium-definition` (field-level rendering), `plutonium-controller` (presentation hooks like `present_parent?`).
-
-Plutonium uses [Phlex](https://www.phlex.fun/) for all view components. This provides a Ruby-first approach to building HTML with full IDE support and type safety.
-
-## Architecture Overview
-
-```
-Definition
-├── IndexPage    → renders Table
-├── ShowPage     → renders Display
-├── NewPage      → renders Form
-├── EditPage     → renders Form
-└── InteractiveActionPage → renders Form
-```
-
-Each definition has nested classes you can override:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  class IndexPage < IndexPage; end
-  class ShowPage < ShowPage; end
-  class NewPage < NewPage; end
-  class EditPage < EditPage; end
-  class Form < Form; end
-  class Table < Table; end
-  class Display < Display; end
-end
-```
-
-## Page Customization
-
-### Page Configuration
-
-Set page titles and descriptions in definitions:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  # Static titles
-  index_page_title "Blog Posts"
-  index_page_description "Manage all published articles"
-
-  show_page_title "Article Details"
-  new_page_title "Write New Article"
-  edit_page_title "Edit Article"
-
-  # Control breadcrumbs
-  breadcrumbs true          # Global default
-  index_page_breadcrumbs false  # Per-page override
-  show_page_breadcrumbs true
-end
-```
-
-### Custom Page Class
-
-Override page rendering by subclassing:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  class ShowPage < ShowPage
-    private
-
-    # Custom title logic
-    def page_title
-      "#{object.title} - #{object.author.name}"
-    end
-
-    # Add content before the main area
-    def render_before_content
-      div(class: "alert alert-info") {
-        "This post has #{object.comments.count} comments"
-      }
-    end
-
-    # Add content after
-    def render_after_content
-      render RelatedPostsComponent.new(post: object)
-    end
-
-    # Override the toolbar
-    def render_toolbar
-      div(class: "flex gap-2") {
-        button(class: "btn") { "Preview" }
-        button(class: "btn btn-primary") { "Publish" }
-      }
-    end
-  end
-end
-```
-
-### Page Hooks
-
-All pages inherit these customization hooks:
-
-| Hook | Purpose |
-|------|---------|
-| `render_before_header` | Before entire header section |
-| `render_after_header` | After entire header section |
-| `render_before_breadcrumbs` | Before breadcrumbs |
-| `render_after_breadcrumbs` | After breadcrumbs |
-| `render_before_page_header` | Before title/actions |
-| `render_after_page_header` | After title/actions |
-| `render_before_toolbar` | Before toolbar |
-| `render_after_toolbar` | After toolbar |
-| `render_before_content` | Before main content |
-| `render_after_content` | After main content |
-| `render_before_footer` | Before footer |
-| `render_after_footer` | After footer |
-
-### Custom View Files
-
-For complete control, create custom ERB view files that replace the default entirely.
-
-**File locations:**
-
-```
-# Main app (for a PostsController)
-app/views/posts/index.html.erb
-app/views/posts/show.html.erb
-app/views/posts/new.html.erb
-app/views/posts/edit.html.erb
-
-# Portal-specific
-packages/admin_portal/app/views/admin_portal/posts/show.html.erb
-```
-
-**Default view structure:**
-
-The default views simply render the page class:
-
-```erb
-<%# app/views/resource/show.html.erb %>
-<%= render current_definition.show_page_class.new %>
-```
-
-**Custom view example:**
-
-```erb
-<%# app/views/posts/show.html.erb %>
-<div class="max-w-4xl mx-auto">
-  <article class="prose lg:prose-xl">
-    <h1><%= resource_record!.title %></h1>
-    <div class="meta text-gray-500">
-      By <%= resource_record!.author.name %> on <%= resource_record!.created_at.strftime("%B %d, %Y") %>
-    </div>
-    <%= raw resource_record!.content %>
-  </article>
-
-  <div class="mt-8">
-    <%= link_to "Edit", resource_url_for(resource_record!, action: :edit), class: "btn" %>
-    <%= link_to "Back", resource_url_for(Post), class: "btn" %>
-  </div>
-</div>
-```
-
-**Mixing approaches:**
-
-Render the default page with additions:
-
-```erb
-<%# app/views/posts/show.html.erb %>
-<div class="announcement-banner">
-  Special announcement here
-</div>
-
-<%= render current_definition.show_page_class.new %>
-
-<div class="related-posts">
-  <%= render partial: "related_posts", locals: { post: resource_record! } %>
-</div>
-```
-
-## Form Customization
-
-### Custom Form Template
-
-Override how fields are rendered:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  class Form < Form
-    def form_template
-      # Custom layout with sections
-      div(class: "grid grid-cols-2 gap-6") {
-        div {
-          h3(class: "text-lg font-medium") { "Basic Info" }
-          render_resource_field :title
-          render_resource_field :slug
-        }
-
-        div {
-          h3(class: "text-lg font-medium") { "Content" }
-          render_resource_field :content
-        }
-      }
-
-      div(class: "mt-6") {
-        h3(class: "text-lg font-medium") { "Publishing" }
-        render_resource_field :published_at
-        render_resource_field :category
-      }
-
-      render_actions
-    end
-  end
-end
-```
-
-### Form Methods
-
-| Method | Purpose |
-|--------|---------|
-| `render_fields` | Render all permitted fields |
-| `render_resource_field(name)` | Render a single field |
-| `render_actions` | Render submit buttons |
-| `record` | The form object (alias: `object`) |
-| `resource_fields` | List of permitted field names |
-| `resource_definition` | The definition instance |
-
-## Display Customization
-
-### Custom Display Template
-
-Override the show page detail rendering:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  class Display < Display
-    def display_template
-      # Hero section
-      div(class: "bg-gradient-to-r from-blue-500 to-purple-600 p-8 rounded-lg text-white mb-6") {
-        h1(class: "text-3xl font-bold") { object.title }
-        p(class: "mt-2 opacity-90") { object.excerpt }
-      }
-
-      # Main content
-      Block do
-        fields_wrapper do
-          render_resource_field :author
-          render_resource_field :published_at
-          render_resource_field :category
-        end
-      end
-
-      # Full-width content
-      Block do
-        div(class: "prose max-w-none") {
-          raw object.content
-        }
-      end
-
-      # Associations (tabs)
-      render_associations if present_associations?
-    end
-  end
-end
-```
-
-### Display Methods
-
-| Method | Purpose |
-|--------|---------|
-| `render_fields` | Render all permitted fields in a block |
-| `render_resource_field(name)` | Render single field |
-| `render_associations` | Render association tabs |
-| `object` | The record being displayed |
-| `resource_fields` | List of permitted field names |
-| `resource_associations` | List of permitted associations |
-
-## Table Customization
-
-### Custom Table Rendering
-
-Override list page table:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  class Table < Table
-    def view_template
-      render_search_bar
-      render_scopes_bar
-
-      if collection.empty?
-        render_empty_card
-      else
-        # Custom card grid instead of table
-        div(class: "grid grid-cols-3 gap-4") {
-          collection.each do |post|
-            render PostCardComponent.new(post:)
-          end
-        }
-      end
-
-      render_footer
-    end
-  end
-end
-```
-
-### Table Methods
-
-| Method | Purpose |
-|--------|---------|
-| `render_search_bar` | Search input |
-| `render_scopes_bar` | Scope tabs |
-| `render_table` | Default table |
-| `render_empty_card` | Empty state |
-| `render_footer` | Pagination |
-| `collection` | The paginated records |
-| `resource_fields` | Column field names |
-
-## Component Kit
-
-Plutonium provides shorthand methods for common components:
-
-```ruby
-class MyPage < Plutonium::UI::Page::Base
-  def render_content
-    # These are automatically rendered
-    PageHeader(title: "Dashboard")
-
-    Panel(class: "mt-4") {
-      p { "Content here" }
-    }
-
-    Block {
-      TabList(items: tabs)
-    }
-
-    EmptyCard("No items found")
-
-    ActionButton(action, url: "/posts/new")
-  end
-end
-```
-
-Available kit methods:
-- `Breadcrumbs()`
-- `PageHeader(title:, description:, actions:)`
-- `Panel(**attrs)`
-- `Block(**attrs)`
-- `TabList(items:)`
-- `EmptyCard(message)`
-- `ActionButton(action, url:)`
-- `DynaFrameHost(src:, loading:)` - Lazy-loading turbo frame
-- `DynaFrameContent(content) { |frame| ... }` - Frame-aware content wrapper
-- `TableSearchBar()`
-- `TableScopesBar()`
-- `TableInfo(pagy)`
-- `TablePagination(pagy)`
-
-## DynaFrameContent Pattern
-
-`DynaFrameContent` enables frame-aware rendering. For turbo-frame requests, only the content is rendered inside the frame. For regular requests, the full page renders with header/footer.
-
-```ruby
-# How Page::Base uses DynaFrameContent
-def view_template(&block)
-  DynaFrameContent(page_content(block)) do |frame|
-    render_header        # Skipped for frame requests
-    frame.render_content # Always rendered (in turbo-frame for frame requests)
-    render_footer        # Skipped for frame requests
-  end
-end
-```
-
-This pattern means:
-- **Regular page load**: Full page with header, content, footer
-- **Turbo-frame request**: Only `<turbo-frame id="...">` with content inside
-
-All pages automatically inherit this behavior. No special handling needed for modals or frame navigation.
-
-## Custom Components
-
-### Creating a Phlex Component
-
-```ruby
-# app/components/post_card_component.rb
-class PostCardComponent < Plutonium::UI::Component::Base
-  def initialize(post:)
-    @post = post
-  end
-
-  def view_template
-    div(class: "bg-white rounded-lg shadow p-4") {
-      h3(class: "font-bold") { @post.title }
-      p(class: "text-gray-600 mt-2") { @post.excerpt }
-
-      div(class: "mt-4 flex justify-between items-center") {
-        span(class: "text-sm text-gray-500") { @post.published_at&.strftime("%B %d, %Y") }
-        a(href: resource_url_for(@post), class: "text-blue-600") { "Read more" }
-      }
-    }
-  end
-end
-```
-
-### Using in Definitions
-
-Reference components in field definitions:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  # Custom display component
-  display :status, as: StatusBadgeComponent
-
-  # Custom input component
-  input :color, as: ColorPickerComponent
-
-  # Block with component
-  display :metrics do |field|
-    MetricsChartComponent.new(data: field.value)
-  end
-end
-```
-
-## Page Chrome (Shell)
-
-`Plutonium.configuration.shell` controls the layout shipped above the
-resource pages. Default is **`:modern`** (topbar + icon rail) — only
-override to **`:classic`** (legacy header + sidebar) if you're upgrading
-from a pre-`:modern` version and want to preserve the old chrome:
-
-```ruby
-Plutonium.configure do |config|
-  config.shell = :classic
-end
-```
-
-To customize the shipped chrome per-portal, eject the templates:
-
-```bash
-rails generate pu:eject:shell --dest=admin_portal
-```
-
-This copies `_resource_header.html.erb` and `_resource_sidebar.html.erb`
-into the portal's `app/views/plutonium/`. The eject is independent of
-`shell` — you can run it on either.
-
-## Modal & Slideover Forms
-
-The framework's `:new` / `:edit` actions render inline inside a modal.
-Choose the chrome per-resource via the `modal` DSL on the definition:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  modal :slideover    # default — slide-in panel from the right
-  # modal :centered   # centered dialog
-  # modal false       # full standalone page (no modal)
-end
-```
-
-Custom interactive actions render in their own dialog with their own
-`modal:` option (`:centered` default, or `:slideover`).
-
-### Detecting render context in components
-
-Custom pages / forms can branch on render context:
-
-| Helper | True when |
-|--------|-----------|
-| `in_frame?` | Request is targeting a turbo-frame |
-| `in_modal?` | Request is rendering inside a modal/slideover |
-
-Use them to pin action strips, omit nav chrome, or swap layouts.
-
-## Tabs & URL Hash
-
-Show pages with associations render the **Details** tab first followed
-by one tab per permitted association. The active tab is reflected in
-the URL hash (`#products`, `#refund-requests`) so the page deep-links and
-the active state survives reloads / back navigation.
-
-Tab rows scroll horizontally on narrow viewports — they don't wrap.
-
-## Layout Customization
-
-### Eject Layout
-
-Copy the layout template to your project:
-
-```bash
-rails generate pu:eject:layout
-```
-
-This copies `layouts/resource.html.erb` to your portal.
-
-### Custom Layout Class
-
-Override the Phlex layout:
-
-```ruby
-# packages/admin_portal/app/views/layouts/admin_portal/resource_layout.rb
-module AdminPortal
-  class ResourceLayout < Plutonium::UI::Layout::ResourceLayout
-    private
-
-    # Custom body classes
-    def body_attributes
-      {class: "antialiased bg-slate-100 dark:bg-slate-900"}
-    end
-
-    # Add custom header content
-    def render_before_main
-      super
-      render AnnouncementBanner.new if Announcement.active.any?
-    end
-
-    # Custom scripts
-    def render_body_scripts
-      super
-      script(src: "/custom-analytics.js")
-    end
-  end
-end
-```
-
-### Layout Hooks
-
-| Hook | Purpose |
-|------|---------|
-| `render_before_main` | Before main content area |
-| `render_after_main` | After main (modals, etc.) |
-| `render_before_content` | Inside main, before content |
-| `render_after_content` | Inside main, after content |
-| `render_flash` | Flash messages |
-| `render_head` | HTML head section |
-| `render_title` | Page title tag |
-| `render_metatags` | Meta tags |
-| `render_assets` | CSS/JS assets |
-| `render_body_scripts` | Scripts at end of body |
-
-## Available Context
-
-Both ERB views and Phlex components have access to the same context.
-
-### Resource Methods
-
-| Method | Description |
-|--------|-------------|
-| `resource_class` | The model class (e.g., `Post`) |
-| `resource_record!` | Current record (raises if not found) |
-| `resource_record?` | Current record (nil if not found) |
-| `current_parent` | Parent record for nested routes |
-| `current_scoped_entity` | Entity for multi-tenant portals |
-
-### Definition & Policy
-
-| Method | Description |
-|--------|-------------|
-| `current_definition` | Definition instance for current resource |
-| `current_policy` | Policy instance for current record |
-| `current_authorized_scope` | Scoped collection user can access |
-
-### Authentication
-
-| Method | Description |
-|--------|-------------|
-| `current_user` | Authenticated user (if using Rodauth) |
-
-### URL Helpers
-
-| Method | Description |
-|--------|-------------|
-| `resource_url_for(record)` | URL for a record |
-| `resource_url_for(record, action: :edit)` | Action URL for record |
-| `resource_url_for(Model)` | Index URL for model |
-| `resource_url_for(Model, action: :new)` | New URL for model |
-| `resource_url_for(record, parent: parent)` | Nested resource URL |
-
-### Display Helpers
-
-| Method | Description |
-|--------|-------------|
-| `display_name_of(record)` | Human-readable name for record |
-| `resource_name(klass)` | Singular model name |
-| `resource_name_plural(klass)` | Plural model name |
-
-### In Phlex Components
-
-```ruby
-class MyComponent < Plutonium::UI::Component::Base
-  def view_template
-    # All the above methods work directly
-    current_user
-    resource_record!
-    resource_url_for(@post)
-
-    # Rails helpers via helpers proxy
-    helpers.link_to(...)
-    helpers.image_tag(...)
-    helpers.number_to_currency(...)
-  end
-end
-```
-
-### In ERB Views
-
-```erb
-<%# All methods available directly %>
-<%= resource_record!.title %>
-<%= current_user.name %>
-<%= link_to "Edit", resource_url_for(resource_record!, action: :edit) %>
-
-<%# Render Phlex components %>
-<%= render current_definition.show_page_class.new %>
-<%= render MyCustomComponent.new(post: resource_record!) %>
-```
-
-## Portal-Specific Views
-
-Each portal can have its own view overrides:
-
-```ruby
-# Base definition
-class PostDefinition < ResourceDefinition
-  class ShowPage < ShowPage
-    # Default behavior
-  end
-end
-
-# Admin portal override
-class AdminPortal::PostDefinition < ::PostDefinition
-  class ShowPage < ShowPage  # Inherits from ::PostDefinition::ShowPage
-    def render_after_content
-      super
-      render AdminOnlySection.new(post: object)
-    end
-  end
-end
-```
-
-## Related Skills
-
-- `plutonium-forms` - Custom form templates and field builders
-- `plutonium-assets` - TailwindCSS and component theming
-- `plutonium-definition` - Field/input/display configuration
-- `plutonium-definition` - Action buttons and interactions
-- `plutonium-controller` - Presentation hooks (`present_parent?`, etc.)
-- `plutonium-portal` - Portal-specific customization