better_page 2.0.0

data/docs/05-turbo-support.md

@@ -0,0 +1,220 @@
+# Turbo Support
+
+BetterPage provides built-in support for Turbo Frames and Turbo Streams.
+
+### Turbo Helpers in ViewComponents
+
+All BetterPage ViewComponents inherit from `ApplicationViewComponent`, which includes `Turbo::FramesHelper`. This means you have access to Turbo helpers like `turbo_frame_tag` directly in your component templates.
+
+```ruby
+# app/components/better_page/application_view_component.rb
+module BetterPage
+  class ApplicationViewComponent < ViewComponent::Base
+    include Turbo::FramesHelper
+  end
+end
+```
+
+This allows you to use Turbo helpers in any component template:
+
+```erb
+<%# In any component .html.erb template %>
+<%= turbo_frame_tag "my_frame" do %>
+  <!-- Content -->
+<% end %>
+```
+
+--------------------------------
+
+### Overview
+
+| Method Type | Use Case | Returns |
+|-------------|----------|---------|
+| `frame_*` | Lazy loading, navigation | Single Hash |
+| `stream_*` | Real-time updates, form responses | Array of Hashes |
+
+--------------------------------
+
+### Turbo Frame - Lazy Load Component
+
+Use `frame_<action>(:component)` to get a single component for Turbo Frame.
+
+```ruby
+# In controller
+def table
+  @products = Product.all
+  component = Products::IndexPage.new(@products, current_user).frame_index(:table)
+
+  render component[:klass].new(**component[:config])
+end
+
+# frame_index(:table) returns:
+# {
+#   component: :table,
+#   config: { items: [...], columns: [...] },
+#   klass: TableComponent,
+#   target: "better_page_table"
+# }
+```
+
+--------------------------------
+
+### Turbo Frame View Setup
+
+```erb
+<turbo-frame id="better_page_table" src="<%= table_products_path %>" loading="lazy">
+  <p>Loading products...</p>
+</turbo-frame>
+```
+
+--------------------------------
+
+### Turbo Stream - Update Multiple Components
+
+Use `stream_<action>(*components)` to get multiple components for Turbo Stream.
+
+```ruby
+# In controller
+def refresh
+  @products = Product.filtered(params)
+  components = Products::IndexPage.new(@products, current_user).stream_index(:table, :statistics)
+
+  respond_to do |format|
+    format.turbo_stream do
+      render turbo_stream: components.map { |c|
+        turbo_stream.replace(c[:target], c[:klass].new(**c[:config]))
+      }
+    end
+  end
+end
+
+# stream_index(:table, :statistics) returns:
+# [
+#   { component: :table, config: {...}, klass: TableComponent, target: "better_page_table" },
+#   { component: :statistics, config: {...}, klass: StatsComponent, target: "better_page_statistics" }
+# ]
+```
+
+--------------------------------
+
+### Turbo Stream View Setup
+
+```erb
+<div id="better_page_alerts">
+  <%# Alerts rendered here %>
+</div>
+
+<div id="better_page_statistics">
+  <%# Statistics rendered here %>
+</div>
+
+<div id="better_page_table">
+  <%# Table rendered here %>
+</div>
+
+<div id="better_page_pagination">
+  <%# Pagination rendered here %>
+</div>
+```
+
+--------------------------------
+
+### Dynamic Methods by Page Type
+
+Methods are generated based on the page's main action.
+
+| Page Type | Main Action | Frame Method | Stream Method |
+|-----------|-------------|--------------|---------------|
+| IndexBasePage | `index` | `frame_index(:component)` | `stream_index(*components)` |
+| ShowBasePage | `show` | `frame_show(:component)` | `stream_show(*components)` |
+| FormBasePage | `form` | `frame_form(:component)` | `stream_form(*components)` |
+| CustomBasePage | `custom` | `frame_custom(:component)` | `stream_custom(*components)` |
+
+--------------------------------
+
+### Custom Action Methods
+
+If you define a custom action, turbo methods work automatically.
+
+```ruby
+class Reports::DailyPage < CustomBasePage
+  register_component :chart, default: {}
+
+  def daily
+    build_page
+  end
+
+  def chart
+    { type: :line, data: @data }
+  end
+end
+
+# Usage
+page = Reports::DailyPage.new(@data)
+page.frame_daily(:chart)           # Single component
+page.stream_daily(:chart, :summary) # Multiple components
+```
+
+--------------------------------
+
+### Customize Default Stream Components
+
+Override `stream_components` to define defaults.
+
+```ruby
+class Products::IndexPage < IndexBasePage
+  def stream_components
+    %i[alerts statistics table pagination]
+  end
+end
+
+# Now stream_index without arguments returns these four
+page.stream_index  # => alerts, statistics, table, pagination
+```
+
+--------------------------------
+
+### Customize Frame Target
+
+Override `frame_target` to customize DOM element IDs.
+
+```ruby
+def frame_target(name)
+  "products_#{name}"  # "products_table" instead of "better_page_table"
+end
+```
+
+--------------------------------
+
+### Customize Stream Target
+
+Override `stream_target` to customize DOM element IDs.
+
+```ruby
+def stream_target(name)
+  "products_#{name}"
+end
+```
+
+--------------------------------
+
+### Available Turbo Stream Actions
+
+```ruby
+components.each do |c|
+  # Replace - replaces entire element
+  turbo_stream.replace(c[:target], c[:klass].new(**c[:config]))
+
+  # Update - replaces content only
+  turbo_stream.update(c[:target], c[:klass].new(**c[:config]))
+
+  # Append - adds after existing content
+  turbo_stream.append(c[:target], c[:klass].new(**c[:config]))
+
+  # Prepend - adds before existing content
+  turbo_stream.prepend(c[:target], c[:klass].new(**c[:config]))
+
+  # Remove - removes element
+  turbo_stream.remove(c[:target])
+end
+```

data/docs/06-compliance-analyzer.md

@@ -0,0 +1,147 @@
+# Compliance Analyzer
+
+The Compliance Analyzer checks that pages follow BetterPage architecture rules.
+
+### Run Compliance Analyzer
+
+```bash
+rake better_page:compliance:analyze
+```
+
+--------------------------------
+
+### Run in Verbose Mode
+
+```bash
+VERBOSE=true rake better_page:compliance:analyze
+```
+
+--------------------------------
+
+### Architecture Rules
+
+Pages must follow these rules:
+
+1. **No database queries** - Data passed via constructor
+2. **No business logic** - UI configuration only
+3. **No service layer access** - No service objects
+4. **Hash-only structures** - No OpenStruct/Struct
+5. **Separate panels for checkboxes** - Checkbox/radio fields in separate panels
+
+--------------------------------
+
+### Required Component Methods
+
+Each page type must implement required methods.
+
+| Page Type | Required Methods |
+|-----------|-----------------|
+| IndexPage | `header`, `table` |
+| ShowPage | `header` |
+| FormPage | `header`, `panels` |
+| CustomPage | `content` |
+
+--------------------------------
+
+### Forbidden Database Patterns
+
+```ruby
+# WRONG - Database queries in page
+def header
+  { title: "#{User.count} Users" }
+end
+
+def table
+  { items: User.where(active: true) }
+end
+
+# CORRECT - Data passed via constructor
+def initialize(users, stats)
+  @users = users
+  @stats = stats
+end
+
+def header
+  { title: "#{@stats[:count]} Users" }
+end
+
+def table
+  { items: @users }
+end
+```
+
+--------------------------------
+
+### Forbidden Business Logic Patterns
+
+```ruby
+# WRONG - Business logic in page
+def calculate_total      # Business calculation
+def process_data         # Business processing
+def validate_user        # Validation logic
+def save_record          # Persistence
+
+# WRONG - Service access
+def header
+  result = UserService.new.get_stats
+  { title: result[:title] }
+end
+```
+
+--------------------------------
+
+### Forbidden External Dependencies
+
+```ruby
+# WRONG - External HTTP clients
+Net::HTTP.get(...)
+HTTParty.get(...)
+Faraday.get(...)
+
+# WRONG - External services
+Redis.current.get(...)
+```
+
+--------------------------------
+
+### Compliance Report Output
+
+```
+SUMMARY
+=======
+Total pages analyzed: 25
+[OK] Fully compliant: 20 (80.0%)
+[WARN] With warnings: 3 (12.0%)
+[ERROR] With errors: 2 (8.0%)
+
+CRITICAL ISSUES
+===============
+- app/pages/admin/users/index_page.rb
+  - Database queries forbidden in Page
+  - Missing required component method: table
+
+RECOMMENDATIONS
+===============
+1. Remove database queries from Pages
+2. Remove business logic - keep UI configuration only
+3. Implement required component methods
+```
+
+--------------------------------
+
+### Programmatic Usage
+
+```ruby
+analyzer = BetterPage::Compliance::Analyzer.new
+
+# Analyze single page
+result = analyzer.analyze_page("app/pages/admin/users/index_page.rb")
+puts result[:status]    # :compliant, :warning, or :error
+puts result[:issues]    # Array of issue messages
+puts result[:warnings]  # Array of warning messages
+
+# Analyze all pages
+analyzer.analyze_all
+puts analyzer.compliant_count
+puts analyzer.error_count
+```

data/docs/07-configuration.md

@@ -0,0 +1,157 @@
+# Configuration
+
+BetterPage uses a hybrid configuration system that combines global configuration with local customization.
+
+### Configuration Levels
+
+Components can be registered at three levels:
+
+1. **Gem Defaults** - Built-in components registered by `BetterPage::DefaultComponents`
+2. **Global Configuration** - User customizations in `config/initializers/better_page.rb`
+3. **Local Classes** - Components in base page classes or individual pages
+
+--------------------------------
+
+### Global Configuration
+
+Configure BetterPage in your initializer:
+
+```ruby
+# config/initializers/better_page.rb
+BetterPage.configure do |config|
+  # Register a new component
+  config.register_component :sidebar, default: { enabled: false } do
+    optional(:enabled).filled(:bool)
+    optional(:items).array(:hash)
+  end
+
+  # Map component to page types
+  config.allow_components :index, :sidebar
+  config.allow_components :show, :sidebar
+
+  # Make component required for a page type
+  config.require_components :index, :sidebar
+
+  # Override a default component
+  config.register_component :pagination, default: { enabled: true, per_page: 25 }
+end
+```
+
+--------------------------------
+
+### Configuration API
+
+| Method | Description |
+|--------|-------------|
+| `register_component(name, options, &schema)` | Register a component with optional schema |
+| `allow_components(page_type, *names)` | Map components to a page type |
+| `require_components(page_type, *names)` | Mark components as required for a page type |
+| `components_for(page_type)` | Get component names for a page type |
+| `component(name)` | Get a component definition |
+| `component_required?(page_type, name)` | Check if component is required |
+
+--------------------------------
+
+### Page Type DSL
+
+Base page classes use `page_type` to inherit components from global configuration:
+
+```ruby
+# app/pages/index_base_page.rb
+class IndexBasePage < ApplicationPage
+  page_type :index  # Inherits components mapped to :index
+
+  # Add local components
+  register_component :quick_filters, default: []
+
+  def index
+    build_page
+  end
+
+  def view_component_class
+    BetterPage::IndexViewComponent
+  end
+end
+```
+
+Available page types: `:index`, `:show`, `:form`, `:custom`
+
+--------------------------------
+
+### Default Components
+
+BetterPage registers these components by default:
+
+**Shared Components:**
+- `header` - Page header with title, breadcrumbs, actions
+- `alerts` - Alert messages (default: `[]`)
+- `footer` - Footer section (default: `{ enabled: false }`)
+- `statistics` - Statistic cards (default: `[]`)
+- `overview` - Overview section (default: `{ enabled: false }`)
+
+**Index Components:**
+- `table` - Data table with columns and actions
+- `metrics` - Metric displays
+- `tabs` - Tab navigation
+- `search` - Search configuration
+- `pagination` - Pagination settings
+- `calendar` - Calendar view
+- `modals` - Modal dialogs
+- `split_view` - Split view layout
+
+**Show Components:**
+- `content_sections` - Content sections
+
+**Form Components:**
+- `panels` - Form panels with fields
+- `errors` - Error display
+
+**Custom Components:**
+- `content` - Custom content
+
+--------------------------------
+
+### Sync Generator
+
+Check for new components when upgrading BetterPage:
+
+```bash
+rails generate better_page:sync
+```
+
+This compares your configuration with gem defaults and reports:
+- New components available from the gem
+- Components you've customized
+
+--------------------------------
+
+### Example: Adding a Custom Component
+
+```ruby
+# 1. Register in initializer
+# config/initializers/better_page.rb
+BetterPage.configure do |config|
+  config.register_component :activity_feed, default: { events: [], limit: 10 } do
+    optional(:events).array(:hash)
+    optional(:limit).filled(:integer)
+  end
+  config.allow_components :show, :activity_feed
+end
+
+# 2. Use in a page
+# app/pages/admin/users/show_page.rb
+class Admin::Users::ShowPage < ShowBasePage
+  def activity_feed
+    {
+      events: @user.recent_activities.map { |a| format_activity(a) },
+      limit: 20
+    }
+  end
+
+  private
+
+  def format_activity(activity)
+    { type: activity.type, message: activity.message, at: activity.created_at }
+  end
+end
+```

data/guide/00-README.md

@@ -0,0 +1,32 @@
+# BetterPage Guides
+
+Step-by-step tutorials for building pages with BetterPage.
+
+### Guide Index
+
+| Guide | Description |
+|-------|-------------|
+| [01-quick-start](01-quick-start.md) | Get started in 5 minutes |
+| [02-building-index-page](02-building-index-page.md) | Build feature-rich list pages |
+| [03-building-show-page](03-building-show-page.md) | Build detail pages with content sections |
+| [04-building-form-page](04-building-form-page.md) | Build new and edit forms |
+| [05-custom-pages](05-custom-pages.md) | Build dashboards and reports |
+| [06-best-practices](06-best-practices.md) | Guidelines for maintainable pages |
+
+--------------------------------
+
+### Prerequisites
+
+Before starting, ensure you have:
+- Rails >= 8.1.1
+- BetterPage gem installed
+- Basic familiarity with Ruby and Rails
+
+--------------------------------
+
+### Getting Help
+
+If you need assistance:
+- Check the [documentation](../docs/00-README.md)
+- Review the example code in each guide
+- Run compliance checks: `rake better_page:analyze`

data/guide/01-quick-start.md

@@ -0,0 +1,148 @@
+# Quick Start Guide
+
+Get started with BetterPage in 5 minutes.
+
+### Install the Gem
+
+```ruby
+# Gemfile
+gem "better_page"
+```
+
+```bash
+bundle install
+rails g better_page:install
+```
+
+This creates:
+- `app/pages/application_page.rb` - Base page class
+- `app/pages/index_base_page.rb` - Base for index pages
+- `app/pages/show_base_page.rb` - Base for show pages
+- `app/pages/form_base_page.rb` - Base for form pages
+- `app/pages/custom_base_page.rb` - Base for custom pages
+- `config/initializers/better_page.rb` - Configuration file
+
+--------------------------------
+
+### Generate Your First Page
+
+```bash
+rails g better_page:page Admin::Products index show new edit
+```
+
+This creates:
+- `app/pages/admin/products/index_page.rb`
+- `app/pages/admin/products/show_page.rb`
+- `app/pages/admin/products/new_page.rb`
+- `app/pages/admin/products/edit_page.rb`
+
+--------------------------------
+
+### Basic Index Page
+
+```ruby
+# app/pages/admin/products/index_page.rb
+module Admin
+  module Products
+    class IndexPage < IndexBasePage
+      def initialize(products, metadata = {})
+        @products = products
+        @user = metadata[:user]
+        super(products, metadata)
+      end
+
+      private
+
+      def header
+        {
+          title: "Products",
+          breadcrumbs: [
+            { label: "Home", path: "/" },
+            { label: "Products" }
+          ],
+          actions: [
+            { label: "New Product", path: "/products/new", icon: "plus", style: :primary }
+          ]
+        }
+      end
+
+      def table
+        {
+          items: @products,
+          columns: [
+            { key: :name, label: "Name", type: :link },
+            { key: :price, label: "Price", format: :currency },
+            { key: :active, label: "Status", type: :boolean }
+          ],
+          empty_state: {
+            icon: "box",
+            title: "No products yet",
+            message: "Create your first product to get started"
+          }
+        }
+      end
+    end
+  end
+end
+```
+
+--------------------------------
+
+### Use in Controller
+
+```ruby
+# app/controllers/admin/products_controller.rb
+class Admin::ProductsController < ApplicationController
+  def index
+    products = Product.all
+    @page = Admin::Products::IndexPage.new(products, user: current_user).index
+  end
+end
+```
+
+--------------------------------
+
+### Render in View
+
+```erb
+<%# app/views/admin/products/index.html.erb %>
+<%= render "shared/page", page: @page %>
+```
+
+Or access data directly:
+
+```erb
+<h1><%= @page[:header][:title] %></h1>
+
+<table>
+  <thead>
+    <tr>
+      <% @page[:table][:columns].each do |column| %>
+        <th><%= column[:label] %></th>
+      <% end %>
+    </tr>
+  </thead>
+  <tbody>
+    <% @page[:table][:items].each do |item| %>
+      <tr>
+        <% @page[:table][:columns].each do |column| %>
+          <td><%= item.send(column[:key]) %></td>
+        <% end %>
+      </tr>
+    <% end %>
+  </tbody>
+</table>
+```
+
+--------------------------------
+
+### Verify Compliance
+
+```bash
+rake better_page:analyze
+```
+
+This ensures your pages follow the architecture rules:
+- No database queries in pages
+- No business logic
+- Data passed via constructor