better_page 2.0.0

data/docs/02-component-registry.md

@@ -0,0 +1,192 @@
+# Component Registry
+
+BetterPage uses a hybrid component registration system with three levels.
+
+### Registration Levels
+
+Components can be registered at three levels:
+
+1. **Global Configuration** - In `config/initializers/better_page.rb`
+2. **Base Page Classes** - In local base pages like `IndexBasePage`
+3. **Individual Pages** - In specific page classes
+
+--------------------------------
+
+### Global Configuration (Initializer)
+
+Register components globally in your initializer. These are available to all pages of the mapped type.
+
+```ruby
+# config/initializers/better_page.rb
+BetterPage.configure do |config|
+  # Add a custom component with schema
+  config.register_component :sidebar, default: { enabled: false } do
+    optional(:enabled).filled(:bool)
+    optional(:items).array(:hash)
+  end
+
+  # Map to page types
+  config.allow_components :index, :sidebar
+  config.allow_components :show, :sidebar
+
+  # Make required for specific page types
+  config.require_components :index, :sidebar
+end
+```
+
+--------------------------------
+
+### Base Page Classes (page_type DSL)
+
+Local base classes use `page_type` to inherit components from global configuration.
+
+```ruby
+# app/pages/index_base_page.rb
+class IndexBasePage < ApplicationPage
+  page_type :index
+
+  # Add component only for index pages
+  register_component :quick_filters, default: []
+end
+```
+
+--------------------------------
+
+### Individual Pages
+
+Register components specific to a single page.
+
+```ruby
+class Admin::Users::IndexPage < IndexBasePage
+  # Component only for this page
+  register_component :user_stats, default: nil
+
+  def user_stats
+    { active_count: @users.active.count }
+  end
+end
+```
+
+--------------------------------
+
+### Register Component with Schema
+
+Use dry-schema for validation. Required components raise errors if nil.
+
+```ruby
+register_component :header, required: true do
+  required(:title).filled(:string)
+  optional(:description).filled(:string)
+  optional(:breadcrumbs).array(:hash)
+  optional(:actions).array(:hash)
+end
+```
+
+--------------------------------
+
+### Register Optional Component with Default
+
+Optional components use default values when method is not defined.
+
+```ruby
+register_component :alerts, default: []
+
+register_component :pagination, default: { enabled: false } do
+  optional(:enabled).filled(:bool)
+  optional(:page).filled(:integer)
+  optional(:total_pages).filled(:integer)
+end
+```
+
+--------------------------------
+
+### Implement Component Methods
+
+Define methods matching the component names in your page class.
+
+```ruby
+class Admin::Users::IndexPage < IndexBasePage
+  def initialize(users, current_user)
+    @users = users
+    @current_user = current_user
+  end
+
+  private
+
+  def header
+    { title: "Users", breadcrumbs: breadcrumbs_config }
+  end
+
+  def table
+    { items: @users, columns: columns_config }
+  end
+
+  # Optional - uses default [] if not defined
+  def statistics
+    [{ label: "Total", value: @users.count, icon: "users" }]
+  end
+end
+```
+
+--------------------------------
+
+### Build Page Method
+
+The build_page method collects all registered components.
+
+```ruby
+def index
+  build_page
+end
+
+# Returns:
+# {
+#   header: { title: "Users", breadcrumbs: [...] },
+#   table: { items: [...], columns: [...] },
+#   statistics: [...],
+#   pagination: { enabled: false },
+#   alerts: [],
+#   ...
+# }
+```
+
+--------------------------------
+
+### Component Inheritance
+
+Components are inherited through the class hierarchy and merged with global configuration.
+
+```ruby
+# Global configuration provides components for each page_type
+# app/pages/index_base_page.rb inherits from ApplicationPage and uses page_type :index
+# Individual pages inherit from their base class
+
+class Admin::Products::IndexPage < IndexBasePage
+  # Gets components from:
+  # 1. Global config mapped to :index (header, table, statistics, pagination, etc.)
+  # 2. IndexBasePage local components
+  # 3. ApplicationPage components (alerts, footer)
+end
+```
+
+### Check for New Components
+
+When upgrading BetterPage, check for new default components:
+
+```bash
+rails generate better_page:sync
+```
+
+--------------------------------
+
+### Validation Error Handling
+
+Validation errors raise in development, log warnings in production.
+
+```ruby
+# Development - raises exception
+BetterPage::ValidationError: Component :header validation failed: {:title=>["is missing"]}
+
+# Production - logs warning
+[BetterPage] Component :header validation failed: {:title=>["is missing"]}
+```

data/docs/03-base-pages.md

@@ -0,0 +1,238 @@
+# Base Pages Reference
+
+### Page Types Overview
+
+BetterPage provides four base page classes, generated locally in your `app/pages/` folder.
+
+| Type | Base Class | Required Components | Use Case |
+|------|-----------|---------------------|----------|
+| Index | `IndexBasePage` | `header`, `table` | List views |
+| Show | `ShowBasePage` | `header` | Detail views |
+| Form | `FormBasePage` | `header`, `panels` | New/Edit forms |
+| Custom | `CustomBasePage` | `content` | Dashboards, reports |
+
+### Inheritance Hierarchy
+
+```
+BetterPage::BasePage (gem)
+        │
+        ▼
+ApplicationPage (app/pages/)
+        │
+        ├── IndexBasePage (page_type :index)
+        ├── ShowBasePage (page_type :show)
+        ├── FormBasePage (page_type :form)
+        └── CustomBasePage (page_type :custom)
+```
+
+--------------------------------
+
+### IndexBasePage Components
+
+Components available for list/index pages.
+
+| Component | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `header` | Yes | - | Page header with title, breadcrumbs, actions |
+| `table` | Yes | - | Table with items, columns, actions |
+| `alerts` | No | `[]` | Alert messages |
+| `statistics` | No | `[]` | Statistic cards |
+| `metrics` | No | `[]` | Metric displays |
+| `tabs` | No | `{ enabled: false }` | Tab navigation |
+| `search` | No | `{ enabled: false }` | Search configuration |
+| `pagination` | No | `{ enabled: false }` | Pagination settings |
+| `footer` | No | `{ enabled: false }` | Footer section |
+
+--------------------------------
+
+### IndexBasePage Example
+
+```ruby
+class Admin::Users::IndexPage < IndexBasePage
+  def initialize(users, metadata = {})
+    @users = users
+    @user = metadata[:user]
+    super(users, metadata)
+  end
+
+  private
+
+  def header
+    { title: "Users", actions: [{ label: "New", path: new_admin_user_path }] }
+  end
+
+  def table
+    { items: @users, columns: table_columns, empty_state: empty_config }
+  end
+
+  def statistics
+    [
+      { label: "Total", value: @users.size, icon: "users" },
+      { label: "Active", value: @users.count(&:active?), icon: "check" }
+    ]
+  end
+
+  def pagination
+    { enabled: true, page: 1, total_pages: 10 }
+  end
+end
+```
+
+--------------------------------
+
+### ShowBasePage Components
+
+Components available for detail/show pages.
+
+| Component | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `header` | Yes | - | Page header with title, metadata, actions |
+| `alerts` | No | `[]` | Alert messages |
+| `statistics` | No | `[]` | Statistic cards |
+| `overview` | No | `{ enabled: false }` | Overview section |
+| `content_sections` | No | `[]` | Content sections (info grids, text) |
+| `footer` | No | `{ enabled: false }` | Footer section |
+
+--------------------------------
+
+### ShowBasePage Helper Methods
+
+```ruby
+# Convert hash to info grid format
+info_grid_content_format({ "Name" => "John", "Email" => "john@example.com" })
+# => [{ name: "Name", value: "John" }, { name: "Email", value: "john@example.com" }]
+
+# Build content section
+content_section_format(
+  title: "Details",
+  icon: "info",
+  color: "blue",
+  type: :info_grid,
+  content: { "Name" => "John" }
+)
+
+# Build statistic
+statistic_format(label: "Total", value: 100, icon: "users", color: "blue")
+
+# Build action button
+action_format(path: edit_path, label: "Edit", icon: "edit", style: "primary")
+```
+
+--------------------------------
+
+### FormBasePage Components
+
+Components available for new/edit form pages.
+
+| Component | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `header` | Yes | - | Form header with title, description |
+| `panels` | Yes | - | Form panels with fields |
+| `alerts` | No | `[]` | Alert messages |
+| `errors` | No | `nil` | Custom error configuration |
+| `footer` | No | `{ primary_action: {...} }` | Form footer with buttons |
+
+--------------------------------
+
+### FormBasePage Helper Methods
+
+```ruby
+# Build a field
+field_format(name: :email, type: :email, label: "Email", required: true)
+
+# Build a panel
+panel_format(title: "Basic Info", fields: [...], description: "Enter details")
+```
+
+**Important**: Checkbox and radio fields must be in separate panels.
+
+--------------------------------
+
+### FormBasePage Example
+
+```ruby
+class Admin::Users::NewPage < FormBasePage
+  def initialize(user, metadata = {})
+    @user = user
+    @current_user = metadata[:user]
+    super(user, metadata)
+  end
+
+  private
+
+  def header
+    { title: "New User", description: "Create a new user account" }
+  end
+
+  def panels
+    [
+      panel_format(
+        title: "Account Details",
+        fields: [
+          field_format(name: :email, type: :email, label: "Email", required: true),
+          field_format(name: :name, type: :text, label: "Name", required: true)
+        ]
+      ),
+      panel_format(
+        title: "Settings",
+        fields: [
+          field_format(name: :active, type: :checkbox, label: "Active")
+        ]
+      )
+    ]
+  end
+end
+```
+
+--------------------------------
+
+### CustomBasePage Components
+
+Components available for custom pages.
+
+| Component | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `header` | No | `nil` | Optional page header |
+| `content` | Yes | - | Custom content configuration |
+| `footer` | No | `nil` | Optional footer |
+
+--------------------------------
+
+### CustomBasePage Helper Methods
+
+```ruby
+# Build a widget
+widget_format(title: "Stats", type: :chart, data: {...})
+
+# Build a chart
+chart_format(title: "Revenue", type: :line, data: { labels: [...], datasets: [...] })
+```
+
+--------------------------------
+
+### CustomBasePage Example
+
+```ruby
+class Admin::DashboardPage < CustomBasePage
+  def initialize(data, metadata = {})
+    @data = data
+    @user = metadata[:user]
+    super(data, metadata)
+  end
+
+  private
+
+  def header
+    { title: "Dashboard" }
+  end
+
+  def content
+    {
+      widgets: [
+        widget_format(title: "Users", type: :counter, data: { value: @data[:users_count] }),
+        chart_format(title: "Revenue", type: :line, data: @data[:revenue_chart])
+      ]
+    }
+  end
+end
+```

data/docs/04-schema-validation.md

@@ -0,0 +1,180 @@
+# Schema Validation
+
+BetterPage uses [dry-schema](https://dry-rb.org/gems/dry-schema/) for component validation.
+
+### String Type
+
+```ruby
+register_component :header, required: true do
+  required(:title).filled(:string)
+  optional(:subtitle).filled(:string)
+end
+```
+
+--------------------------------
+
+### Integer Type
+
+```ruby
+register_component :pagination do
+  optional(:page).filled(:integer)
+  optional(:per_page).filled(:integer)
+end
+```
+
+--------------------------------
+
+### Boolean Type
+
+```ruby
+register_component :tabs do
+  optional(:enabled).filled(:bool)
+end
+```
+
+--------------------------------
+
+### Array Type
+
+```ruby
+register_component :header do
+  optional(:breadcrumbs).array(:hash)
+  optional(:actions).array(:hash)
+end
+```
+
+--------------------------------
+
+### Hash Type with Nested Schema
+
+```ruby
+register_component :table do
+  optional(:empty_state).hash do
+    optional(:icon).filled(:string)
+    optional(:title).filled(:string)
+    optional(:message).filled(:string)
+  end
+end
+```
+
+--------------------------------
+
+### Required vs Optional Fields
+
+```ruby
+# Must be present and non-empty
+required(:title).filled(:string)
+
+# If present, must be non-empty string
+optional(:subtitle).filled(:string)
+
+# Array of hash objects
+optional(:columns).array(:hash)
+```
+
+--------------------------------
+
+### Complex Nested Structure
+
+```ruby
+register_component :footer do
+  optional(:primary_action).hash do
+    required(:label).filled(:string)
+    optional(:style).filled(:string)
+  end
+  optional(:secondary_actions).array(:hash)
+end
+```
+
+--------------------------------
+
+### Header Component Schema Example
+
+```ruby
+register_component :header, required: true do
+  required(:title).filled(:string)
+  optional(:description).filled(:string)
+  optional(:breadcrumbs).array(:hash)
+  optional(:metadata).array(:hash)
+  optional(:actions).array(:hash)
+end
+```
+
+Valid:
+
+```ruby
+def header
+  {
+    title: "Users",
+    breadcrumbs: [
+      { label: "Home", path: "/" },
+      { label: "Users", path: "/users" }
+    ],
+    actions: [
+      { label: "New", path: "/users/new", icon: "plus" }
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Table Component Schema Example
+
+```ruby
+register_component :table, required: true do
+  required(:items).value(:array)
+  optional(:columns).array(:hash)
+  optional(:actions)
+  optional(:empty_state).hash do
+    optional(:icon).filled(:string)
+    optional(:title).filled(:string)
+    optional(:message).filled(:string)
+    optional(:action).hash
+  end
+end
+```
+
+Valid:
+
+```ruby
+def table
+  {
+    items: @users,
+    columns: [
+      { key: :name, label: "Name", type: :link },
+      { key: :email, label: "Email", type: :text }
+    ],
+    empty_state: {
+      icon: "users",
+      title: "No users found",
+      message: "Create your first user to get started"
+    }
+  }
+end
+```
+
+--------------------------------
+
+### Validation Error Handling
+
+```ruby
+# Development - raises exception
+BetterPage::ValidationError: Component :header validation failed: {:title=>["is missing"]}
+
+# Production - logs warning
+[BetterPage] Component :header validation failed: {:title=>["is missing"]}
+```
+
+--------------------------------
+
+### Components Without Schema
+
+Components can be registered without schema validation.
+
+```ruby
+register_component :alerts, default: []
+register_component :custom_data, default: nil
+```
+
+These components accept any value without validation.