plutonium 0.50.0 → 0.51.0

data/docs/reference/views/index.md

@@ -1,544 +0,0 @@
-# Views Reference
-
-Complete reference for UI customization with Phlex components.
-
-## Overview
-
-Plutonium uses [Phlex](https://www.phlex.fun/) for all view components. Customization happens through:
-- Definition nested classes (pages, forms, tables, displays)
-- Page hooks for injecting content
-- Custom Phlex components
-- ERB view overrides
-
-## Architecture
-
-```
-Definition
-├── IndexPage    → renders Table
-├── ShowPage     → renders Display
-├── NewPage      → renders Form
-├── EditPage     → renders Form
-└── InteractiveActionPage → renders Interaction Form
-```
-
-## Page Configuration
-
-Set titles and descriptions in definitions:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  # Page 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"
-
-  # Breadcrumbs
-  breadcrumbs true              # Global default
-  index_page_breadcrumbs false  # Per-page override
-  show_page_breadcrumbs true
-end
-```
-
-## Custom Page Classes
-
-Override page rendering by defining nested classes in your definition:
-
-```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 |
-
-## Form Customization
-
-Override form rendering in your definition:
-
-```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` / `object` | The form object |
-| `resource_fields` | List of permitted field names |
-| `resource_definition` | The definition instance |
-
-## Display Customization
-
-Override 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
-
-Override index 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 view_template
-    # 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:
-
-| Method | Purpose |
-|--------|---------|
-| `Breadcrumbs()` | Navigation breadcrumbs |
-| `PageHeader(title:, description:, actions:)` | Page header with actions |
-| `Panel(**attrs)` | Content panel |
-| `Block(**attrs)` | Content block |
-| `TabList(items:)` | Tab navigation |
-| `EmptyCard(message)` | Empty state card |
-| `ActionButton(action, url:)` | Action button |
-| `DynaFrameHost(src:, loading:)` | Lazy-loading turbo frame |
-| `DynaFrameContent(content) { \|frame\| ... }` | Frame-aware content wrapper |
-| `TableSearchBar()` | Search bar for tables |
-| `TableScopesBar()` | Scope tabs for tables |
-| `TableInfo(pagy)` | Pagination info |
-| `TablePagination(pagy)` | Pagination links |
-| `FrameNavigatorPanel(title:, src:, panel_id:)` | Frame navigation panel |
-
-## 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 (wrapped 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 - modals, lazy-loaded frames, and navigation all work correctly without special handling.
-
-## 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 Components in 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. The default is **`:modern`** (topbar + icon rail) — leave it alone unless you're upgrading from a pre-`:modern` version and want to keep the legacy header + sidebar:
-
-```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/`.
-
-## Modal & Slideover Forms
-
-Framework-provided `:new` / `:edit` actions render inline inside a modal. Choose the chrome per-resource via [`modal`](/reference/definition/#form-configuration) on the definition (`:slideover` default, `:centered`, or `false`).
-
-Custom interactive actions render in their own dialog. Each action carries its own [`modal:` option](/reference/definition/actions#action-options) (`:centered` default, or `:slideover`).
-
-### Detecting Render Context
-
-In custom Page / Form components:
-
-| 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 rather than wrapping.
-
-## Show Page Metadata Panel
-
-The [`metadata` DSL](/reference/definition/#show-page-metadata-panel) on the definition opts a resource into a right-side aside that renders selected fields as label/value rows alongside the main details. The aside collapses to a single-column stack below the `lg` breakpoint and disappears entirely when no listed field is permitted by policy.
-
-## Layout Customization
-
-### Custom Layout Class
-
-```ruby
-# packages/admin_portal/app/views/layouts/admin_portal/resource_layout.rb
-module AdminPortal
-  class ResourceLayout < Plutonium::UI::Layout::ResourceLayout
-    private
-
-    # Custom main content area classes
-    def main_attributes
-      mix(super, { class: "pt-20 lg:ml-64" })
-    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_head` | HTML head section |
-| `render_title` | Page title tag |
-| `render_assets` | CSS/JS assets |
-| `render_body_scripts` | Scripts at end of body |
-
-## Custom ERB Views
-
-For complete control, create custom ERB view files:
-
-```
-# Main app (for a PostsController)
-app/views/posts/index.html.erb
-app/views/posts/show.html.erb
-
-# Portal-specific
-packages/admin_portal/app/views/admin_portal/posts/show.html.erb
-```
-
-The default views 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>
-    <%= 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>
-```
-
-## Available 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 |
-
-### 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
-    # Plutonium methods work directly
-    current_user
-    resource_record!
-    resource_url_for(@post)
-
-    # Rails helpers via helpers proxy
-    helpers.link_to(...)
-    helpers.image_tag(...)
-  end
-end
-```
-
-## Portal-Specific Views
-
-Each portal can override views:
-
-```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
-
-- [Forms Reference](./forms) - Custom form templates and field builders
-- [Theming Guide](/guides/theming) - TailwindCSS and styling
-- [Fields Reference](/reference/definition/fields) - Field configuration