better_page 2.0.0

data/lib/better_page/custom_base_page.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module BetterPage
+  # Base class for custom pages that don't fit index/show/form patterns.
+  # Uses page_type to inherit components from global configuration.
+  #
+  # Available components (from configuration):
+  # - content (required): Main custom content section
+  # - header, footer, alerts
+  #
+  # @example
+  #   class Admin::Dashboard::CustomPage < CustomBasePage
+  #     def header
+  #       { title: "Dashboard", breadcrumbs: [] }
+  #     end
+  #
+  #     def content
+  #       { widgets: [...], charts: [...] }
+  #     end
+  #   end
+  #
+  class CustomBasePage < BasePage
+    page_type :custom
+
+    # Main method that builds the complete custom page configuration
+    # @return [Hash] complete custom page configuration with :klass for rendering
+    def custom
+      build_page
+    end
+
+    # Note: frame_custom and stream_custom are dynamically generated via method_missing in ComponentRegistry
+    # For custom pages with different action names (e.g. #daily), frame_daily/stream_daily work automatically
+    # Usage:
+    #   page.frame_custom(:content)        # Single component for Turbo Frame
+    #   page.stream_custom                  # All stream components for Turbo Streams
+    #   page.frame_daily(:chart)           # For a page with #daily method
+    #   page.stream_daily(:chart, :summary) # Multiple components for Turbo Streams
+
+    # The ViewComponent class used to render this custom page
+    # @return [Class] BetterPage::CustomViewComponent
+    def view_component_class
+      return BetterPage::CustomViewComponent if defined?(BetterPage::CustomViewComponent)
+
+      raise NotImplementedError, "BetterPage::CustomViewComponent not found. Run: rails g better_page:install"
+    end
+
+    # Components to include in stream updates by default
+    # @return [Array<Symbol>]
+    def stream_components
+      %i[alerts content]
+    end
+
+    protected
+
+    # Helper to build a widget section
+    # @param title [String] widget title
+    # @param type [Symbol] widget type
+    # @param data [Hash, Array] widget data
+    # @param options [Hash] additional options
+    # @return [Hash] formatted widget
+    def widget_format(title:, type:, data:, **options)
+      {
+        title: title,
+        type: type,
+        data: data,
+        **options
+      }
+    end
+
+    # Helper to build a chart configuration
+    # @param title [String] chart title
+    # @param type [Symbol] chart type (:line, :bar, :pie, etc.)
+    # @param data [Hash] chart data with labels and datasets
+    # @param options [Hash] additional chart options
+    # @return [Hash] formatted chart
+    def chart_format(title:, type:, data:, **options)
+      {
+        title: title,
+        type: type,
+        data: data,
+        **options
+      }
+    end
+  end
+end

data/lib/better_page/default_components.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module BetterPage
+  # Registers all default components provided by the gem.
+  # Called automatically during Rails initialization before user initializers.
+  #
+  # Components are organized by page type:
+  # - Index: header, table, alerts, statistics, metrics, tabs, search, pagination, overview, calendar, footer, modals, split_view
+  # - Show: header, alerts, statistics, overview, content_sections, footer
+  # - Form: header, alerts, errors, panels, footer
+  # - Custom: header, content, footer, alerts
+  #
+  module DefaultComponents
+    class << self
+      # Register all default components
+      # @return [void]
+      def register!
+        BetterPage.configure do |config|
+          register_shared_components(config)
+          register_index_components(config)
+          register_show_components(config)
+          register_form_components(config)
+          register_custom_components(config)
+
+          map_components_to_page_types(config)
+          set_required_components(config)
+        end
+      end
+
+      # Get all default component names
+      # @return [Array<Symbol>]
+      def component_names
+        %i[
+          header table alerts statistics metrics tabs search pagination
+          overview calendar footer modals split_view content_sections
+          errors panels content
+        ]
+      end
+
+      private
+
+      def register_shared_components(config)
+        # Header - used by all page types
+        config.register_component :header do
+          required(:title).filled(:string)
+          optional(:breadcrumbs).array(:hash)
+          optional(:metadata).array(:hash)
+          optional(:actions).array(:hash)
+          optional(:description).filled(:string)
+        end
+
+        # Alerts - used by all page types
+        config.register_component :alerts, default: []
+
+        # Footer - used by all page types
+        config.register_component :footer, default: { enabled: false }
+
+        # Statistics - used by index and show
+        config.register_component :statistics, default: []
+
+        # Overview - used by index and show
+        config.register_component :overview, default: { enabled: false }
+      end
+
+      def register_index_components(config)
+        # Table - primary component for index pages
+        config.register_component :table 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
+
+        # Metrics section
+        config.register_component :metrics, default: []
+
+        # Tabs navigation
+        config.register_component :tabs, default: { enabled: false, current_tab: "all", tabs: [] } do
+          optional(:enabled).filled(:bool)
+          optional(:current_tab).filled(:string)
+          optional(:tabs).array(:hash)
+        end
+
+        # Search section
+        config.register_component :search, default: {
+          enabled: false,
+          placeholder: "Search...",
+          current_search: "",
+          results_count: 0
+        } do
+          optional(:enabled).filled(:bool)
+          optional(:placeholder).filled(:string)
+          optional(:current_search).maybe(:string)
+          optional(:results_count).filled(:integer)
+        end
+
+        # Pagination
+        config.register_component :pagination, default: { enabled: false } do
+          optional(:enabled).filled(:bool)
+          optional(:page).filled(:integer)
+          optional(:total_pages).filled(:integer)
+          optional(:total_count).filled(:integer)
+          optional(:per_page).filled(:integer)
+        end
+
+        # Calendar view
+        config.register_component :calendar, default: {
+          enabled: false,
+          current_date: nil,
+          view_type: "month",
+          events: [],
+          navigation: {}
+        } do
+          optional(:enabled).filled(:bool)
+          optional(:current_date)
+          optional(:view_type).filled(:string)
+          optional(:events).array(:hash)
+          optional(:navigation).hash
+        end
+
+        # Modals
+        config.register_component :modals, default: []
+
+        # Split view
+        config.register_component :split_view, default: {
+          enabled: false,
+          selected_id: nil,
+          items: [],
+          list_title: "Items",
+          detail_title: "Details",
+          list_item_config: nil,
+          detail_path: nil,
+          empty_state: {
+            icon: "inbox",
+            title: "Select an item",
+            message: "Click on an item from the list to see its details"
+          }
+        }
+      end
+
+      def register_show_components(config)
+        # Content sections
+        config.register_component :content_sections, default: []
+      end
+
+      def register_form_components(config)
+        # Errors component
+        config.register_component :errors, default: nil
+
+        # Panels component
+        config.register_component :panels
+      end
+
+      def register_custom_components(config)
+        # Content component
+        config.register_component :content
+      end
+
+      def map_components_to_page_types(config)
+        # Index page components
+        config.allow_components :index,
+          :header, :table, :alerts, :statistics, :metrics,
+          :tabs, :search, :pagination, :overview, :calendar,
+          :footer, :modals, :split_view
+
+        # Show page components
+        config.allow_components :show,
+          :header, :alerts, :statistics, :overview,
+          :content_sections, :footer
+
+        # Form page components
+        config.allow_components :form,
+          :header, :alerts, :errors, :panels, :footer
+
+        # Custom page components
+        config.allow_components :custom,
+          :header, :content, :footer, :alerts
+      end
+
+      def set_required_components(config)
+        # Index pages require header and table
+        config.require_components :index, :header, :table
+
+        # Show pages require header
+        config.require_components :show, :header
+
+        # Form pages require header and panels
+        config.require_components :form, :header, :panels
+
+        # Custom pages require content
+        config.require_components :custom, :content
+      end
+    end
+  end
+end

data/lib/better_page/form_base_page.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module BetterPage
+  # Base class for form pages (new/edit).
+  # Uses page_type to inherit components from global configuration.
+  #
+  # FORM ORGANIZATION RULES (MANDATORY):
+  # =====================================
+  #
+  # RULE 1: INPUT TYPE SEPARATION
+  # - CHECKBOX fields must be grouped in dedicated panels, never mixed with other inputs
+  # - RADIO BUTTON fields must be grouped in dedicated panels, never mixed with other inputs
+  # - Text, email, select, textarea, number, date can be mixed together
+  #
+  # CORRECT EXAMPLE:
+  # [
+  #   {
+  #     title: 'Basic Information',
+  #     fields: [
+  #       { name: :name, type: :text, ... },      # OK
+  #       { name: :email, type: :email, ... }     # OK
+  #     ]
+  #   },
+  #   {
+  #     title: 'Settings',                        # Separate panel
+  #     fields: [
+  #       { name: :is_primary, type: :checkbox, ... },  # OK
+  #       { name: :is_active, type: :checkbox, ... }    # OK
+  #     ]
+  #   }
+  # ]
+  #
+  # WRONG EXAMPLE:
+  # [
+  #   {
+  #     title: 'Information',
+  #     fields: [
+  #       { name: :name, type: :text, ... },           # OK
+  #       { name: :is_primary, type: :checkbox, ... }  # VIOLATION - checkbox with text
+  #     ]
+  #   }
+  # ]
+  #
+  # Available components (from configuration):
+  # - header (required): Form header with title, description, breadcrumbs
+  # - panels (required): Form panels with fields
+  # - alerts, errors, footer
+  #
+  # @example
+  #   class Admin::Users::FormPage < FormBasePage
+  #     def header
+  #       { title: @item.new_record? ? "New User" : "Edit User" }
+  #     end
+  #
+  #     def panels
+  #       [{ title: "Basic Info", fields: [...] }]
+  #     end
+  #   end
+  #
+  class FormBasePage < BasePage
+    page_type :form
+
+    # Override the global footer default with form-specific default
+    register_component :footer, default: {
+      primary_action: { label: "Save", style: :primary },
+      secondary_actions: []
+    }
+
+    # Main method that builds the complete form page configuration
+    # @return [Hash] complete form page configuration with :klass for rendering
+    def form
+      result = build_page
+      validate_form_panels_rules(result[:panels]) if result[:panels]
+      result
+    end
+
+    # Note: frame_form and stream_form are dynamically generated via method_missing in ComponentRegistry
+    # Usage:
+    #   page.frame_form(:panels)            # Single component for Turbo Frame
+    #   page.stream_form                     # All stream components for Turbo Streams
+    #   page.stream_form(:panels, :errors)   # Specific components for Turbo Streams
+
+    # The ViewComponent class used to render this form page
+    # @return [Class] BetterPage::FormViewComponent
+    def view_component_class
+      return BetterPage::FormViewComponent if defined?(BetterPage::FormViewComponent)
+
+      raise NotImplementedError, "BetterPage::FormViewComponent not found. Run: rails g better_page:install"
+    end
+
+    # Components to include in stream updates by default
+    # @return [Array<Symbol>]
+    def stream_components
+      %i[alerts errors panels]
+    end
+
+    protected
+
+    # Validates that all panels follow the input separation rules
+    # Logs warnings in development mode when rules are violated
+    # @param panels [Array<Hash>] panels to validate
+    # @return [void]
+    def validate_form_panels_rules(panels)
+      return unless defined?(Rails) && Rails.env.development?
+
+      panels.each_with_index do |panel, index|
+        next unless panel[:fields].is_a?(Array)
+
+        checkbox_count = panel[:fields].count { |field| field[:type] == :checkbox }
+        radio_count = panel[:fields].count { |field| field[:type] == :radio }
+        other_count = panel[:fields].count { |field| %i[checkbox radio].exclude?(field[:type]) }
+
+        # RULE 1: Checkboxes must be in separate panels
+        if checkbox_count.positive? && other_count.positive?
+          Rails.logger.warn "[BetterPage::FormBasePage] RULE VIOLATION in panel '#{panel[:title]}' (#{index}): " \
+                            "checkboxes mixed with other inputs (checkboxes: #{checkbox_count}, others: #{other_count})"
+        end
+
+        # RULE 1: Radio buttons must be in separate panels
+        if radio_count.positive? && other_count.positive?
+          Rails.logger.warn "[BetterPage::FormBasePage] RULE VIOLATION in panel '#{panel[:title]}' (#{index}): " \
+                            "radio buttons mixed with other inputs (radio: #{radio_count}, others: #{other_count})"
+        end
+      end
+    end
+
+    # Helper to build a form field
+    # @param name [Symbol] field name
+    # @param type [Symbol] field type (:text, :email, :select, :checkbox, etc.)
+    # @param label [String] field label
+    # @param options [Hash] additional options (required, placeholder, collection, etc.)
+    # @return [Hash] formatted field
+    def field_format(name:, type:, label:, **options)
+      {
+        name: name,
+        type: type,
+        label: label,
+        **options
+      }
+    end
+
+    # Helper to build a form panel
+    # @param title [String] panel title
+    # @param fields [Array<Hash>] panel fields
+    # @param description [String, nil] panel description
+    # @param icon [String, nil] panel icon
+    # @return [Hash] formatted panel
+    def panel_format(title:, fields:, description: nil, icon: nil)
+      panel = {
+        title: title,
+        fields: fields
+      }
+      panel[:description] = description if description
+      panel[:icon] = icon if icon
+      panel
+    end
+
+    # Default breadcrumbs for forms
+    # @return [Array<Hash>] empty breadcrumbs
+    def default_breadcrumbs
+      []
+    end
+
+    # Extract resource name from class name
+    # @return [String] downcased resource name
+    def resource_name
+      self.class.name.split("::").last.gsub(/Page$/, "").downcase
+    end
+  end
+end

data/lib/better_page/index_base_page.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module BetterPage
+  # Base class for index/list pages.
+  # Uses page_type to inherit components from global configuration.
+  #
+  # Available components (from configuration):
+  # - header (required): Page header with title, breadcrumbs, metadata, actions
+  # - table (required): Table with items, columns, actions, empty_state
+  # - alerts, statistics, metrics, tabs, search, pagination
+  # - overview, calendar, footer, modals, split_view
+  #
+  # @example
+  #   class Admin::Users::IndexPage < IndexBasePage
+  #     def header
+  #       { title: "Users", breadcrumbs: [], actions: [] }
+  #     end
+  #
+  #     def table
+  #       { items: @users, columns: [...], empty_state: {...} }
+  #     end
+  #   end
+  #
+  class IndexBasePage < BasePage
+    page_type :index
+
+    # Main method that builds the complete index page configuration
+    # @return [Hash] complete index page configuration with :klass for rendering
+    def index
+      build_page
+    end
+
+    # Note: frame_index and stream_index are dynamically generated via method_missing in ComponentRegistry
+    # Usage:
+    #   page.frame_index(:table)              # Single component for Turbo Frame
+    #   page.stream_index                      # All stream components for Turbo Streams
+    #   page.stream_index(:table, :pagination) # Specific components for Turbo Streams
+
+    # The ViewComponent class used to render this index page
+    # @return [Class] BetterPage::IndexViewComponent
+    def view_component_class
+      return BetterPage::IndexViewComponent if defined?(BetterPage::IndexViewComponent)
+
+      raise NotImplementedError, "BetterPage::IndexViewComponent not found. Run: rails g better_page:install"
+    end
+
+    # Components to include in stream updates by default
+    # @return [Array<Symbol>]
+    def stream_components
+      %i[alerts statistics table pagination]
+    end
+
+    protected
+
+    # Helper for split view empty state
+    # @param icon [String] icon name
+    # @param title [String] title text
+    # @param message [String] message text
+    # @return [Hash] empty state configuration
+    def split_view_empty_state_format(icon: "hand-pointer", title: "Select an item",
+                                      message: "Click on an item from the list to see its details")
+      {
+        icon: icon,
+        title: title,
+        message: message
+      }
+    end
+  end
+end

data/lib/better_page/railtie.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module BetterPage
+  class Railtie < ::Rails::Railtie
+    # Add app/pages to the autoload paths
+    # Must run before :set_autoload_paths to avoid FrozenError in Rails 8+
+    initializer "better_page.autoload_paths", before: :set_autoload_paths do |app|
+      pages_path = Rails.root.join("app", "pages")
+      if pages_path.exist?
+        app.config.autoload_paths << pages_path.to_s
+        app.config.eager_load_paths << pages_path.to_s
+      end
+    end
+
+    # Register default components before user initializers
+    # This allows users to override or extend defaults in their initializers
+    initializer "better_page.register_defaults", before: :load_config_initializers do
+      BetterPage::DefaultComponents.register!
+      BetterPage.defaults_registered!
+    end
+
+    # Load rake tasks
+    rake_tasks do
+      load "tasks/better_page.rake"
+    end
+
+    # Add generators path
+    generators do
+      require "generators/better_page/install_generator"
+      require "generators/better_page/page_generator"
+      require "generators/better_page/sync_generator"
+    end
+  end
+end

data/lib/better_page/show_base_page.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module BetterPage
+  # Base class for show/detail pages.
+  # Uses page_type to inherit components from global configuration.
+  #
+  # Available components (from configuration):
+  # - header (required): Page header with title, breadcrumbs, metadata, actions
+  # - alerts, statistics, overview, content_sections, footer
+  #
+  # @example
+  #   class Admin::Users::ShowPage < ShowBasePage
+  #     def header
+  #       { title: @user.name, breadcrumbs: [], actions: [] }
+  #     end
+  #
+  #     def content_sections
+  #       [{ title: "Details", type: :info_grid, items: [...] }]
+  #     end
+  #   end
+  #
+  class ShowBasePage < BasePage
+    page_type :show
+
+    # Main method that builds the complete show page configuration
+    # @return [Hash] complete show page configuration with :klass for rendering
+    def show
+      build_page
+    end
+
+    # Note: frame_show and stream_show are dynamically generated via method_missing in ComponentRegistry
+    # Usage:
+    #   page.frame_show(:overview)                    # Single component for Turbo Frame
+    #   page.stream_show                               # All stream components for Turbo Streams
+    #   page.stream_show(:overview, :content_sections) # Specific components for Turbo Streams
+
+    # The ViewComponent class used to render this show page
+    # @return [Class] BetterPage::ShowViewComponent
+    def view_component_class
+      return BetterPage::ShowViewComponent if defined?(BetterPage::ShowViewComponent)
+
+      raise NotImplementedError, "BetterPage::ShowViewComponent not found. Run: rails g better_page:install"
+    end
+
+    # Components to include in stream updates by default
+    # @return [Array<Symbol>]
+    def stream_components
+      %i[alerts statistics overview content_sections]
+    end
+
+    protected
+
+    # Helper to convert hash to info grid format
+    # @param hash [Hash] key-value pairs to convert
+    # @return [Array<Hash>] formatted info grid items
+    def info_grid_content_format(hash)
+      hash.map { |name, value| { name: name, value: value } }
+    end
+
+    # Helper to build content section
+    # @param title [String] section title
+    # @param icon [String] section icon
+    # @param color [String] section color
+    # @param type [Symbol] section type (:info_grid, :text_content, :custom)
+    # @param content [Hash, Array, nil] section content
+    # @return [Hash] formatted content section
+    def content_section_format(title:, icon:, color:, type:, content: nil)
+      section = {
+        title: title,
+        icon: icon,
+        color: color,
+        type: type
+      }
+
+      if type == :info_grid && content.is_a?(Array) && content.first.is_a?(Hash) && content.first.key?(:name)
+        section[:items] = content
+      elsif type == :info_grid && content.is_a?(Hash)
+        section[:items] = info_grid_content_format(content)
+      elsif type == :info_grid
+        section[:items] = content
+      else
+        section[:content] = content
+      end
+
+      section
+    end
+
+    # Helper to build statistic card
+    # @param label [String] statistic label
+    # @param value [String, Numeric] statistic value
+    # @param icon [String] statistic icon
+    # @param color [String] statistic color
+    # @return [Hash] formatted statistic
+    def statistic_format(label:, value:, icon:, color:)
+      {
+        label: label,
+        value: value,
+        icon: icon,
+        color: color
+      }
+    end
+
+    # Helper to build header action
+    # @param path [String] action path
+    # @param label [String] action label
+    # @param icon [String] action icon
+    # @param style [String] action style
+    # @param method [Symbol] HTTP method
+    # @return [Hash] formatted action
+    def action_format(path:, label:, icon:, style:, method: :get)
+      {
+        path: path,
+        label: label,
+        icon: icon,
+        style: style,
+        method: method
+      }
+    end
+  end
+end

data/lib/better_page/validation_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BetterPage
+  # Error raised when component validation fails in development mode
+  class ValidationError < StandardError
+  end
+end

data/lib/better_page/version.rb

@@ -0,0 +1,3 @@
+module BetterPage
+  VERSION = "2.0.0"
+end