better_page 2.0.0

data/lib/better_page.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "better_page/version"
+require "better_page/railtie" if defined?(Rails::Railtie)
+
+module BetterPage
+  # Core components
+  autoload :ValidationError, "better_page/validation_error"
+  autoload :Config, "better_page/config"
+  autoload :ComponentRegistry, "better_page/component_registry"
+  autoload :ComponentDefinition, "better_page/component_registry"
+  autoload :Configuration, "better_page/configuration"
+  autoload :DefaultComponents, "better_page/default_components"
+
+  # Base page classes
+  autoload :BasePage, "better_page/base_page"
+  autoload :IndexBasePage, "better_page/index_base_page"
+  autoload :ShowBasePage, "better_page/show_base_page"
+  autoload :FormBasePage, "better_page/form_base_page"
+  autoload :CustomBasePage, "better_page/custom_base_page"
+
+  # Compliance module
+  module Compliance
+    autoload :Analyzer, "better_page/compliance/analyzer"
+  end
+
+  # ViewComponent classes (loaded from user's app/components directory)
+  # These are defined when the user runs the install generator
+  module Ui
+    # UI components are autoloaded from the user's application
+  end
+
+  class << self
+    # Access the global configuration
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure BetterPage components
+    #
+    # @yield [Configuration] yields the configuration object
+    # @return [Configuration]
+    #
+    # @example
+    #   BetterPage.configure do |config|
+    #     config.register_component :sidebar, default: { enabled: false }
+    #     config.allow_components :index, :sidebar
+    #   end
+    #
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    # Reset configuration to empty state
+    # Used primarily for testing
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Check if default components have been registered
+    #
+    # @return [Boolean]
+    def defaults_registered?
+      @defaults_registered ||= false
+    end
+
+    # Mark defaults as registered
+    # Called by railtie after registering default components
+    #
+    # @return [void]
+    def defaults_registered!
+      @defaults_registered = true
+    end
+  end
+end

data/lib/generators/better_page/component_generator.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module BetterPage
+  module Generators
+    class ComponentGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :component_name, type: :string, required: true,
+                                desc: "Name of the component to install (e.g., 'header', 'table', 'index')"
+
+      desc "Installs a specific BetterPage ViewComponent"
+
+      MAIN_COMPONENTS = %w[index show form custom].freeze
+      UI_COMPONENTS = %w[
+        header table alerts statistics pagination
+        panel field errors overview content_section
+        widget footer tabs drawer
+      ].freeze
+
+      def validate_component
+        return if valid_component?
+
+        say_error "Unknown component: #{component_name}"
+        say ""
+        say "Available main components: #{MAIN_COMPONENTS.join(', ')}"
+        say "Available UI components: #{UI_COMPONENTS.join(', ')}"
+        say ""
+        say "Or use 'all' to install all components."
+        raise Thor::Error, "Invalid component name"
+      end
+
+      def create_component_directories
+        empty_directory "app/components/better_page"
+        empty_directory "app/components/better_page/ui" if ui_component? || install_all?
+      end
+
+      def install_component
+        if install_all?
+          install_all_components
+        elsif main_component?
+          install_main_component
+        else
+          install_ui_component
+        end
+      end
+
+      def show_post_install_message
+        say ""
+        say "Component(s) installed successfully!", :green
+        say ""
+        say "You can customize the components in app/components/better_page/"
+        say ""
+      end
+
+      private
+
+      def valid_component?
+        install_all? || main_component? || ui_component?
+      end
+
+      def install_all?
+        component_name.downcase == "all"
+      end
+
+      def main_component?
+        MAIN_COMPONENTS.include?(normalized_name)
+      end
+
+      def ui_component?
+        UI_COMPONENTS.include?(normalized_name)
+      end
+
+      def normalized_name
+        @normalized_name ||= component_name.downcase.gsub(/_component$/, "").gsub(/_view_component$/, "")
+      end
+
+      def install_all_components
+        MAIN_COMPONENTS.each { |name| copy_main_component(name) }
+        UI_COMPONENTS.each { |name| copy_ui_component(name) }
+      end
+
+      def install_main_component
+        copy_main_component(normalized_name)
+      end
+
+      def install_ui_component
+        copy_ui_component(normalized_name)
+      end
+
+      def copy_main_component(name)
+        template "view_components/#{name}_view_component.rb.tt",
+                 "app/components/better_page/#{name}_view_component.rb"
+        template "view_components/#{name}_view_component.html.erb.tt",
+                 "app/components/better_page/#{name}_view_component.html.erb"
+        say "  Installed: #{name}_view_component", :green
+      end
+
+      def copy_ui_component(name)
+        template "view_components/ui/#{name}_component.rb.tt",
+                 "app/components/better_page/ui/#{name}_component.rb"
+        template "view_components/ui/#{name}_component.html.erb.tt",
+                 "app/components/better_page/ui/#{name}_component.html.erb"
+        say "  Installed: ui/#{name}_component", :green
+
+        # Install dropdown controller if table component is installed
+        install_dropdown_controller if name == "table"
+
+        # Install drawer controller if drawer component is installed
+        install_drawer_controller if name == "drawer"
+      end
+
+      def install_dropdown_controller
+        return if File.exist?(Rails.root.join("app/javascript/controllers/dropdown_controller.js"))
+
+        copy_file "javascript/controllers/dropdown_controller.js",
+                  "app/javascript/controllers/dropdown_controller.js"
+        say "  Installed: dropdown_controller.js (Stimulus)", :green
+      end
+
+      def install_drawer_controller
+        return if File.exist?(Rails.root.join("app/javascript/controllers/drawer_controller.js"))
+
+        copy_file "javascript/controllers/drawer_controller.js",
+                  "app/javascript/controllers/drawer_controller.js"
+        say "  Installed: drawer_controller.js (Stimulus)", :green
+      end
+    end
+  end
+end

data/lib/generators/better_page/install_generator.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module BetterPage
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the app/pages directory, ApplicationPage base class, base page classes, initializer, and ViewComponents"
+
+      class_option :skip_components, type: :boolean, default: false,
+                                     desc: "Skip installing ViewComponents"
+
+      def create_pages_directory
+        empty_directory "app/pages"
+      end
+
+      def create_initializer
+        template "better_page_initializer.rb.tt", "config/initializers/better_page.rb"
+      end
+
+      def create_application_page
+        template "application_page.rb.tt", "app/pages/application_page.rb"
+      end
+
+      def create_base_pages
+        template "index_base_page.rb.tt", "app/pages/index_base_page.rb"
+        template "show_base_page.rb.tt", "app/pages/show_base_page.rb"
+        template "form_base_page.rb.tt", "app/pages/form_base_page.rb"
+        template "custom_base_page.rb.tt", "app/pages/custom_base_page.rb"
+      end
+
+      def create_view_components
+        return if options[:skip_components]
+
+        # Create main directory structure
+        empty_directory "app/components/better_page"
+        empty_directory "app/components/better_page/ui"
+
+        # Copy base component first (all components inherit from this)
+        template "view_components/application_view_component.rb.tt",
+                 "app/components/better_page/application_view_component.rb"
+
+        # Copy main view components
+        copy_view_component "index_view_component"
+        copy_view_component "show_view_component"
+        copy_view_component "form_view_component"
+        copy_view_component "custom_view_component"
+
+        # Copy UI components
+        ui_components.each do |component|
+          copy_ui_component component
+        end
+      end
+
+      def create_stimulus_controllers
+        return if options[:skip_components]
+
+        # Create directory for BetterPage controllers
+        empty_directory "app/javascript/controllers/better_page"
+
+        # Copy Stimulus controllers for interactive components
+        copy_file "javascript/controllers/dropdown_controller.js",
+                  "app/javascript/controllers/better_page/dropdown_controller.js"
+        copy_file "javascript/controllers/index.js",
+                  "app/javascript/controllers/better_page/index.js"
+
+        # Add import to the main controllers/index.js if it exists
+        controllers_index = "app/javascript/controllers/index.js"
+        if File.exist?(Rails.root.join(controllers_index))
+          append_to_file controllers_index, <<~JS
+
+            // BetterPage controllers
+            import { registerBetterPageControllers } from "./better_page"
+            registerBetterPageControllers(application)
+          JS
+        end
+      end
+
+      def show_post_install_message
+        say ""
+        say "BetterPage has been installed successfully!", :green
+        say ""
+        say "Created:"
+        say "  - config/initializers/better_page.rb (component configuration)"
+        say "  - app/pages/application_page.rb"
+        say "  - app/pages/index_base_page.rb"
+        say "  - app/pages/show_base_page.rb"
+        say "  - app/pages/form_base_page.rb"
+        say "  - app/pages/custom_base_page.rb"
+        unless options[:skip_components]
+          say "  - app/components/better_page/application_view_component.rb (base component)"
+          say "  - app/components/better_page/ (ViewComponents)"
+          say "  - app/javascript/controllers/better_page/ (Stimulus controllers)"
+          say ""
+          say "ViewComponents and Stimulus controllers have been copied to your project."
+          say "You can customize them to match your design system."
+          say ""
+          say "Note: Make sure you have @hotwired/stimulus installed."
+          say ""
+          say "Alternative: Install via npm instead of copying files:"
+          say "  npm install better-page-stimulus"
+          say "  # or"
+          say "  yarn add better-page-stimulus"
+        end
+        say ""
+        say "Base page classes in app/pages/ can be customized:"
+        say "  - Add custom components with register_component"
+        say "  - Override helper methods"
+        say "  - Customize stream_components"
+        say ""
+        say "You can now generate pages using:"
+        say "  rails g better_page:page Namespace::Resource index show new edit"
+        say ""
+        say "Example:"
+        say "  rails g better_page:page Admin::Users index show new edit"
+        say ""
+        say "To check for gem updates:"
+        say "  rails g better_page:sync"
+        say ""
+        say "To add individual components later:"
+        say "  rails g better_page:component ComponentName"
+        say ""
+      end
+
+      private
+
+      def copy_view_component(name)
+        template "view_components/#{name}.rb.tt", "app/components/better_page/#{name}.rb"
+        template "view_components/#{name}.html.erb.tt", "app/components/better_page/#{name}.html.erb"
+      end
+
+      def copy_ui_component(name)
+        template "view_components/ui/#{name}_component.rb.tt",
+                 "app/components/better_page/ui/#{name}_component.rb"
+        template "view_components/ui/#{name}_component.html.erb.tt",
+                 "app/components/better_page/ui/#{name}_component.html.erb"
+      end
+
+      def ui_components
+        %w[
+          header
+          table
+          alerts
+          statistics
+          pagination
+          panel
+          field
+          errors
+          overview
+          content_section
+          widget
+          footer
+          tabs
+        ]
+      end
+    end
+  end
+end

data/lib/generators/better_page/page_generator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module BetterPage
+  module Generators
+    class PageGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :resource, type: :string, required: true,
+               desc: "The resource name (e.g., Admin::Users or Users)"
+      argument :actions, type: :array, default: [],
+               desc: "The actions to generate (index, show, new, edit, custom)"
+
+      desc "Generates page classes for the specified resource and actions"
+
+      def check_pages_directory
+        unless File.directory?(Rails.root.join("app", "pages"))
+          say "app/pages directory not found. Run 'rails g better_page:install' first.", :red
+          exit 1
+        end
+      end
+
+      def create_page_files
+        actions_to_generate = actions.empty? ? %w[index show new edit] : actions
+
+        actions_to_generate.each do |action|
+          template_name = template_for_action(action)
+          if template_name
+            template "#{template_name}.rb.tt", page_path(action)
+          else
+            say "Unknown action: #{action}. Skipping.", :yellow
+          end
+        end
+      end
+
+      def show_completion_message
+        say ""
+        say "Pages generated successfully!", :green
+        say ""
+      end
+
+      private
+
+      def template_for_action(action)
+        case action.to_s
+        when "index" then "index_page"
+        when "show" then "show_page"
+        when "new" then "new_page"
+        when "edit" then "edit_page"
+        when "custom" then "custom_page"
+        end
+      end
+
+      def page_path(action)
+        File.join("app", "pages", *namespace_path, "#{action}_page.rb")
+      end
+
+      def namespace_path
+        resource.underscore.split("/")
+      end
+
+      def resource_namespace
+        parts = resource.split("::")
+        parts.length > 1 ? parts[0..-2].join("::") : nil
+      end
+
+      def resource_name
+        resource.split("::").last
+      end
+
+      def resource_singular
+        resource_name.singularize.underscore
+      end
+
+      def resource_plural
+        resource_name.pluralize.underscore
+      end
+
+      def full_class_name(action)
+        parts = resource.split("::")
+        parts << "#{action.to_s.camelize}Page"
+        parts.join("::")
+      end
+
+      def module_nesting_start
+        parts = resource.split("::")
+        parts.map { |part| "module #{part}" }.join("\n  ")
+      end
+
+      def module_nesting_end
+        parts = resource.split("::")
+        parts.map { "end" }.join("\n")
+      end
+
+      def class_indent
+        "  " * resource.split("::").length
+      end
+    end
+  end
+end

data/lib/generators/better_page/sync_generator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module BetterPage
+  module Generators
+    # Generator to check for new components available in the BetterPage gem.
+    #
+    # Usage:
+    #   rails g better_page:sync
+    #
+    # This compares the components registered in the gem's DefaultComponents
+    # with those in your application's initializer and base page classes,
+    # showing what's new and what might need updating.
+    #
+    class SyncGenerator < Rails::Generators::Base
+      desc "Check for new components available in BetterPage gem"
+
+      def check_components
+        say ""
+        say "BetterPage Sync Check", :green
+        say "=" * 50
+        say ""
+
+        # Get gem's default component names
+        gem_components = BetterPage::DefaultComponents.component_names
+
+        # Get user's configured components
+        user_components = BetterPage.configuration.component_names
+
+        # Find differences
+        new_in_gem = gem_components - user_components
+        custom_in_user = user_components - gem_components
+
+        if new_in_gem.empty? && custom_in_user.empty?
+          say "Your configuration is up to date!", :green
+          say ""
+        else
+          if new_in_gem.any?
+            say "New components available from gem:", :yellow
+            new_in_gem.each { |c| say "  + #{c}" }
+            say ""
+            say "These components are automatically available via global configuration."
+            say "No action needed unless you want to customize their defaults."
+            say ""
+          end
+
+          if custom_in_user.any?
+            say "Custom components in your configuration:", :cyan
+            custom_in_user.each { |c| say "  * #{c}" }
+            say ""
+          end
+        end
+
+        check_page_type_components
+        check_base_page_files
+      end
+
+      private
+
+      def check_page_type_components
+        say "Page Type Component Mapping:", :green
+        say "-" * 50
+
+        %i[index show form custom].each do |page_type|
+          gem_for_type = BetterPage.configuration.components_for(page_type)
+          say "  #{page_type.to_s.ljust(10)} #{gem_for_type.join(', ')}"
+        end
+
+        say ""
+      end
+
+      def check_base_page_files
+        say "Local Base Page Files:", :green
+        say "-" * 50
+
+        base_files = {
+          "index_base_page.rb" => "app/pages/index_base_page.rb",
+          "show_base_page.rb" => "app/pages/show_base_page.rb",
+          "form_base_page.rb" => "app/pages/form_base_page.rb",
+          "custom_base_page.rb" => "app/pages/custom_base_page.rb"
+        }
+
+        base_files.each do |name, path|
+          full_path = Rails.root.join(path)
+          if File.exist?(full_path)
+            local_components = extract_local_components(full_path)
+            if local_components.any?
+              say "  #{name}: #{local_components.join(', ')}", :cyan
+            else
+              say "  #{name}: (no custom components)", :white
+            end
+          else
+            say "  #{name}: NOT FOUND", :red
+            say "    Run: rails g better_page:install", :yellow
+          end
+        end
+
+        say ""
+      end
+
+      def extract_local_components(file_path)
+        content = File.read(file_path)
+        # Extract component names from register_component calls
+        content.scan(/register_component\s+:(\w+)/).flatten.map(&:to_sym)
+      end
+    end
+  end
+end

data/lib/generators/better_page/templates/application_page.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Base class for all application pages.
+# Add common functionality and helpers here.
+class ApplicationPage < BetterPage::BasePage
+  # Add common helpers for your application here
+  #
+  # Example:
+  # def current_user_name
+  #   @user&.full_name || "Guest"
+  # end
+end

data/lib/generators/better_page/templates/better_page_initializer.rb.tt

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# BetterPage Configuration
+# ========================
+#
+# Default components are registered automatically by the gem.
+# Use this file to:
+#   - Add custom global components
+#   - Override default component settings
+#   - Map custom components to page types
+#
+# Components can also be registered locally in:
+#   - Base page classes (app/pages/*_base_page.rb)
+#   - Individual page classes (for page-specific components)
+
+BetterPage.configure do |config|
+  # ─────────────────────────────────────────────────────────────────
+  # CUSTOM COMPONENTS
+  # ─────────────────────────────────────────────────────────────────
+  #
+  # Register a custom component and allow it for specific page types:
+  #
+  # config.register_component :sidebar, default: { enabled: false } do
+  #   optional(:enabled).filled(:bool)
+  #   optional(:items).array(:hash)
+  # end
+  # config.allow_components :index, :sidebar
+  #
+  # ─────────────────────────────────────────────────────────────────
+  # OVERRIDE DEFAULT COMPONENTS
+  # ─────────────────────────────────────────────────────────────────
+  #
+  # Override a default component's settings:
+  #
+  # config.register_component :pagination, default: { enabled: true, per_page: 25 }
+  #
+  # ─────────────────────────────────────────────────────────────────
+  # EXAMPLES
+  # ─────────────────────────────────────────────────────────────────
+  #
+  # Example: Add a timeline component to show pages
+  #
+  # config.register_component :timeline, default: { events: [] }
+  # config.allow_components :show, :timeline
+  #
+  # Example: Add a dashboard widget to custom pages
+  #
+  # config.register_component :dashboard_widget, default: { enabled: false } do
+  #   optional(:title).filled(:string)
+  #   optional(:data).hash
+  # end
+  # config.allow_components :custom, :dashboard_widget
+end