better_page 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9f95ed70f6d49b9da753f5e9475fb21e8bba223489a9199739e4dafd652fba0
+  data.tar.gz: acf2c99e9cef1c9e7075480c8f2098fe222751e0036acf301514a01cf7feb34e
+SHA512:
+  metadata.gz: fe2ad9fefed3af83c594a31b3a721dc090a59ba006cd22ec1d6d17f6614ab0063d71e8c606564abb201d945c8abb78dceba9162e2eb83b4679f0397cea19ef8d
+  data.tar.gz: b5335b3e3eb1623a6b151f190b91f10364568455f0a9de2d601ba0de890566de3e6074e15594d349f47e05d45c9db42cb670b4753e010de13620bafb6eef43b5

data/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2025-12-01
+
+### Added
+
+- **ViewComponents Library** - Complete set of reusable UI components
+  - **Layout Components**
+    - `AppNavComponent` - Application navigation bar with user menu, notifications, mobile support
+    - `SidebarComponent` - Collapsible sidebar with groups, items, badges, persist state
+    - `DrawerComponent` - Slide-in drawer panels (right/left position)
+  - **UI Components**
+    - `TableComponent` - Data tables with sorting, pagination footer, row actions, selection
+    - `DropdownController` - Stimulus controller for dropdown menus
+
+- **Stimulus Controllers Package** (`better-page-stimulus`)
+  - Published on npm for easy JavaScript integration
+  - Controllers: `dropdown`, `table`, `drawer`, `sidebar`, `app-nav`
+  - Works with Rails importmap or npm/yarn
+
+- **ApplicationViewComponent** - Base class for all ViewComponents
+  - All ViewComponents now inherit from `BetterPage::ApplicationViewComponent` instead of `ViewComponent::Base`
+  - Includes `Turbo::FramesHelper` for Turbo frame/stream support in component templates
+  - Generated automatically by `better_page:install` generator
+
+- **Generator Updates**
+  - Installs Stimulus controllers via generator
+  - Creates ViewComponent previews for development
+
+### Changed
+
+- Minimum Rails version updated to 8.1.1
+- ViewComponent dependency updated to >= 3.0
+
+## [0.1.0] - 2025-01-28
+
+### Added
+
+- **Component Registration DSL** - `register_component` method for declaring UI components with schema validation
+- **Schema Validation** - Integration with dry-schema for automatic component data validation in development
+- **Base Page Classes**
+  - `BetterPage::BasePage` - Foundation class with helper methods
+  - `BetterPage::IndexBasePage` - For list/index views with `header` and `table` components
+  - `BetterPage::ShowBasePage` - For detail views with `header` component
+  - `BetterPage::FormBasePage` - For new/edit forms with `header` and `panels` components
+  - `BetterPage::CustomBasePage` - For dashboards and custom views with `content` component
+- **Compliance Analyzer** - Tool to verify pages follow architecture rules (no database queries, no business logic)
+- **Rails Generators**
+  - `better_page:install` - Sets up `app/pages/` directory and `ApplicationPage` base class
+  - `better_page:page` - Generates page classes for specified actions
+- **Documentation**
+  - API reference in `docs/` folder
+  - Step-by-step guides in `guide/` folder
+- **Rake Tasks**
+  - `better_page:compliance:analyze` - Analyze all pages for compliance issues

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright alessiobussolari
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,357 @@
+# BetterPage
+
+A Rails engine that provides a structured Page Object pattern for building UI configurations. Pages are presentation-layer classes that configure UI without business logic, making your views cleaner and more maintainable.
+
+## Features
+
+- **Component Registration DSL** - Declare UI components with schema validation using dry-schema
+- **Multiple Page Types** - Index, Show, Form, and Custom page base classes
+- **Schema Validation** - Automatic validation of component data in development
+- **Turbo Support** - Built-in support for Turbo Frames and Turbo Streams
+- **Compliance Analyzer** - Ensure pages follow architecture rules
+- **Rails Generators** - Quickly scaffold new pages
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "better_page"
+```
+
+Run:
+
+```bash
+bundle install
+rails generate better_page:install
+```
+
+## Quick Start
+
+### Generate a Page
+
+```bash
+rails generate better_page:page admin/users index show new edit
+```
+
+### Define a Page
+
+```ruby
+# app/pages/admin/users/index_page.rb
+class Admin::Users::IndexPage < IndexBasePage
+  def initialize(users, metadata = {})
+    @users = users
+    @user = metadata[:user]
+    super(users, metadata)
+  end
+
+  private
+
+  def header
+    {
+      title: "Users",
+      breadcrumbs: [{ label: "Admin", path: admin_root_path }],
+      actions: [{ label: "New User", path: new_admin_user_path, icon: "plus" }]
+    }
+  end
+
+  def table
+    {
+      items: @users,
+      columns: [
+        { key: :name, label: "Name", type: :link, path: ->(u) { admin_user_path(u) } },
+        { key: :email, label: "Email", type: :text }
+      ],
+      empty_state: { icon: "users", title: "No users", message: "Create your first user" }
+    }
+  end
+end
+```
+
+### Use in Controller
+
+```ruby
+class Admin::UsersController < ApplicationController
+  def index
+    users = User.all.order(:name)
+    @config = Admin::Users::IndexPage.new(users, user: current_user).index
+    # @config is a BetterPage::Config object
+  end
+end
+```
+
+### Access in View
+
+```erb
+<%# Direct method access %>
+<h1><%= @config.header[:title] %></h1>
+
+<%# Hash-like access (backward compatible) %>
+<h1><%= @config[:header][:title] %></h1>
+
+<% @config.table[:items].each do |user| %>
+  <%= user.name %>
+<% end %>
+```
+
+## Page Types
+
+| 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 |
+
+## BetterPage::Config
+
+When you call a page action (e.g., `page.index`, `page.show`), it returns a `BetterPage::Config` object. This follows the same pattern as `BetterService::Result` and `BetterController::Result`.
+
+### Structure
+
+```ruby
+config = Admin::Users::IndexPage.new(users, user: current_user).index
+
+config.components  # => Hash of all component configurations
+config.meta        # => { page_type: :index, klass: IndexViewComponent }
+```
+
+### Component Access
+
+```ruby
+# Direct method access
+config.header            # => { title: "Users", breadcrumbs: [...] }
+config.table             # => { items: [...], columns: [...] }
+config.statistics        # => [{ label: "Total", value: 100 }]
+
+# Hash-like access (backward compatible)
+config[:header][:title]  # => "Users"
+config.dig(:header, :breadcrumbs, 0, :label)  # => "Admin"
+```
+
+### Meta Access
+
+```ruby
+config.page_type  # => :index, :show, :form, :custom
+config.klass      # => ViewComponent class for rendering
+```
+
+### Destructuring
+
+```ruby
+# Supports destructuring like BetterService::Result
+components, meta = config
+
+components[:header][:title]  # => "Users"
+meta[:page_type]             # => :index
+```
+
+### Component Helpers
+
+```ruby
+# Check if component is present (not nil/empty)
+config.component?(:header)      # => true
+config.component?(:pagination)  # => false if empty
+
+# List all component names
+config.component_names  # => [:header, :table, :statistics, ...]
+
+# Get only present (non-empty) components
+config.present_components  # => { header: {...}, table: {...} }
+
+# Iterate over components
+config.each_component do |name, value|
+  puts "#{name}: #{value}"
+end
+```
+
+### Hash-like Interface
+
+For backward compatibility, Config supports full hash-like access:
+
+```ruby
+config[:header]           # => { title: "Users", ... }
+config.key?(:header)      # => true
+config.dig(:table, :items, 0)  # => first item
+```
+
+## Configuration
+
+BetterPage uses a hybrid configuration system. Default components are registered by the gem, and you can customize them in your initializer:
+
+```ruby
+# config/initializers/better_page.rb
+BetterPage.configure do |config|
+  # Add a custom global component
+  config.register_component :sidebar, default: { enabled: false }
+  config.allow_components :index, :sidebar
+
+  # Override a default component
+  config.register_component :pagination, default: { enabled: true, per_page: 25 }
+end
+```
+
+### Check for Updates
+
+When upgrading BetterPage, check for new components:
+
+```bash
+rails generate better_page:sync
+```
+
+## Component Registration
+
+Components can be registered at three levels:
+
+### 1. Global Configuration (Initializer)
+
+```ruby
+# config/initializers/better_page.rb
+BetterPage.configure do |config|
+  config.register_component :sidebar, default: { enabled: false } do
+    optional(:enabled).filled(:bool)
+    optional(:items).array(:hash)
+  end
+  config.allow_components :index, :sidebar
+end
+```
+
+### 2. Base Page Classes (Local)
+
+```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
+```
+
+### 3. Individual Pages
+
+```ruby
+# app/pages/admin/users/index_page.rb
+class Admin::Users::IndexPage < IndexBasePage
+  # Component only for this specific page
+  register_component :user_stats, default: nil
+
+  def user_stats
+    { active_count: @users.active.count }
+  end
+end
+```
+
+## Architecture Rules
+
+Pages must follow these rules (enforced by compliance analyzer):
+
+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
+
+Run compliance check:
+
+```bash
+rake better_page:compliance:analyze
+```
+
+## ViewComponent Architecture
+
+All UI components inherit from `ApplicationViewComponent`:
+
+```
+ViewComponent::Base
+       │
+       ▼
+BetterPage::ApplicationViewComponent (includes Turbo::FramesHelper)
+       │
+       ├── IndexViewComponent
+       ├── ShowViewComponent
+       ├── FormViewComponent
+       ├── CustomViewComponent
+       └── Ui::* (Header, Table, Drawer, Modal, etc.)
+```
+
+The `ApplicationViewComponent` base class includes `Turbo::FramesHelper`, making Turbo helpers available in all component templates.
+
+## Turbo Support
+
+BetterPage provides built-in support for Turbo Frames and Turbo Streams.
+
+### Turbo Frame (Single Component)
+
+```ruby
+# Controller - lazy load table
+def table
+  component = Products::IndexPage.new(@products, current_user).frame_index(:table)
+  render component[:klass].new(**component[:config])
+end
+```
+
+### Turbo Stream (Multiple Components)
+
+```ruby
+# Controller - update multiple components
+def refresh
+  components = Products::IndexPage.new(@products, current_user).stream_index(:table, :statistics)
+
+  render turbo_stream: components.map { |c|
+    turbo_stream.replace(c[:target], c[:klass].new(**c[:config]))
+  }
+end
+```
+
+Dynamic methods are generated based on your page's main action: `frame_index`, `stream_index`, `frame_show`, `stream_show`, etc.
+
+## Lookbook (Component Preview)
+
+BetterPage includes [Lookbook](https://lookbook.build/) for previewing ViewComponents in development.
+
+```bash
+cd spec/rails_app && bin/rails server -p 3099
+```
+
+Open http://localhost:3099/lookbook to browse component previews.
+
+## Documentation
+
+- **[docs/](docs/)** - API reference and technical documentation
+- **[guide/](guide/)** - Step-by-step guides and tutorials
+
+### Quick Links
+
+- [Getting Started](docs/01-getting-started.md)
+- [Component Registry](docs/02-component-registry.md)
+- [Base Pages Reference](docs/03-base-pages.md)
+- [Schema Validation](docs/04-schema-validation.md)
+- [Turbo Support](docs/05-turbo-support.md)
+- [Compliance Analyzer](docs/06-compliance-analyzer.md)
+- [Configuration](docs/07-configuration.md)
+- [Quick Start Guide](guide/01-quick-start.md)
+- [Building Index Pages](guide/02-building-index-page.md)
+- [Building Form Pages](guide/04-building-form-page.md)
+- [Best Practices](guide/06-best-practices.md)
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 8.1
+- dry-schema ~> 1.13
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -am 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Create a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Author
+
+Alessio Bussolari <alessio.bussolari@pandev.it>

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/docs/00-README.md

@@ -0,0 +1,17 @@
+# BetterPage Documentation
+
+API reference and technical documentation for BetterPage.
+
+## Contents
+
+- [01-getting-started.md](01-getting-started.md) - Installation and basic setup
+- [02-component-registry.md](02-component-registry.md) - Component registration DSL
+- [03-base-pages.md](03-base-pages.md) - Base page classes reference
+- [04-schema-validation.md](04-schema-validation.md) - dry-schema validation
+- [05-turbo-support.md](05-turbo-support.md) - Turbo Frame and Stream support
+- [06-compliance-analyzer.md](06-compliance-analyzer.md) - Compliance analyzer
+
+## Quick Links
+
+- [Guide](../guide/) - Step-by-step tutorials
+- [Context7](../context7/) - LLM-optimized snippets

data/docs/01-getting-started.md

@@ -0,0 +1,137 @@
+# Getting Started
+
+### Install BetterPage Gem
+
+Add BetterPage to your Rails application Gemfile.
+
+```ruby
+gem "better_page"
+```
+
+--------------------------------
+
+### Run Bundle Install
+
+Install the gem and its dependencies.
+
+```bash
+bundle install
+```
+
+--------------------------------
+
+### Run Install Generator
+
+Create the page infrastructure in your application.
+
+```bash
+rails generate 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
+- `app/components/better_page/application_view_component.rb` - Base ViewComponent class (includes `Turbo::FramesHelper`)
+- `app/components/better_page/` - ViewComponents for rendering pages
+
+--------------------------------
+
+### Generate Page Classes
+
+Scaffold page classes for a resource with multiple actions.
+
+```bash
+rails generate better_page:page admin/users index show new edit
+```
+
+This creates:
+- `app/pages/admin/users/index_page.rb`
+- `app/pages/admin/users/show_page.rb`
+- `app/pages/admin/users/new_page.rb`
+- `app/pages/admin/users/edit_page.rb`
+
+--------------------------------
+
+### Basic Page Structure
+
+Pages are presentation-layer classes that configure UI without business logic.
+
+```ruby
+class Admin::Users::IndexPage < IndexBasePage
+  def initialize(users, metadata = {})
+    @users = users
+    @user = metadata[:user]
+    super(users, metadata)
+  end
+
+  private
+
+  def header
+    {
+      title: "Users",
+      breadcrumbs: [{ label: "Home", path: "/" }],
+      actions: [{ label: "New User", path: new_admin_user_path, icon: "plus" }]
+    }
+  end
+
+  def table
+    {
+      items: @users,
+      columns: [
+        { key: :name, label: "Name", type: :link },
+        { key: :email, label: "Email", type: :text }
+      ],
+      empty_state: { icon: "users", title: "No users", message: "No users found" }
+    }
+  end
+end
+```
+
+--------------------------------
+
+### Use Page in Controller
+
+Instantiate the page and call the main action method.
+
+```ruby
+class Admin::UsersController < ApplicationController
+  def index
+    users = User.all
+    @page = Admin::Users::IndexPage.new(users, user: current_user).index
+  end
+
+  def show
+    user = User.find(params[:id])
+    @page = Admin::Users::ShowPage.new(user, user: current_user).show
+  end
+end
+```
+
+--------------------------------
+
+### Access Page Data in View
+
+Use the @page hash to render UI components.
+
+```erb
+<h1><%= @page[:header][:title] %></h1>
+
+<% @page[:table][:items].each do |user| %>
+  <%= user.name %>
+<% end %>
+```
+
+--------------------------------
+
+### 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