power-compass 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62d24dd9988012b6ce11695c503b785d1f0fc662c08708fefad59eaab4d8a96b
+  data.tar.gz: f04fbc2588e8013529171751bf5df84026d5743ef605dc74f7d3cffd974c7d50
+SHA512:
+  metadata.gz: 10be0899560a5fd97c5f14ffcad8208e535cd1b597ef058804806f4b4cc4b0b050126e6e1d108bc304708aaae536d4f19d4c2661a9b65e9a17d960232d1dfa56
+  data.tar.gz: 61b19fa23127e9e6a6c9efff137692ce56ddb95476928bd8136b0b034730a4808a2c9dc8c6683a8a70d79093d152733898ed157cbf39b4207c980aa290112c13

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Carlos Palhares
+
+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,28 @@
+# Compass
+Short description and motivation.
+
+## Usage
+How to use my plugin.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "compass"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install compass
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "bundler/gem_tasks"
+load "rails/tasks/statistics.rake"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new(:rubocop)
+
+task default: %i[rubocop spec]

data/app/controllers/compass/application_controller.rb

@@ -0,0 +1,37 @@
+module Compass
+  # Base compass controller.
+  #
+  # @private
+  class ApplicationController < ActionController::API
+    etag { current_context_id }
+    etag { context_modified_at }
+
+    before_action unless: :authenticate do
+      head(:forbidden)
+    end
+
+    before_action unless: :validate_context_id do
+      head(:bad_request)
+    end
+
+    def authenticate
+      instance_exec(&Compass.config.authenticate)
+    end
+
+    def current_context
+      instance_exec(&Compass.config.context)
+    end
+
+    def current_context_id
+      instance_exec(&Compass.config.context_id)
+    end
+
+    def context_modified_at
+      instance_exec(&Compass.config.modified_at)
+    end
+
+    def validate_context_id
+      current_context_id.to_s.eql?(params[:context_id])
+    end
+  end
+end

data/app/controllers/compass/menu_controller.rb

@@ -0,0 +1,31 @@
+module Compass
+  # Base compass controller.
+  #
+  # @private
+  class MenuController < ApplicationController
+    etag { filter.values.compact }
+    etag { menu_items.maximum(:updated_at) }
+
+    def index
+      expires_in(*Array(Compass.config.menu.cache))
+
+      return unless stale? menu_items, etag: "compass-menu"
+
+      render json: menu_items, filter: filter
+    end
+
+  private
+
+    def menu_items
+      @menu_items ||= Compass::Menu.build(**current_context)
+    end
+
+    def filter
+      {
+        authorized: true,
+        tagged: params[:tagged],
+        sort: params.fetch(:sort, %i[ gravity label ])
+      }
+    end
+  end
+end

data/app/controllers/compass/notification_controller.rb

@@ -0,0 +1,15 @@
+require "compass/notification/provider"
+
+module Compass
+  class NotificationController < ApplicationController
+    def index
+      expires_in(*Array(Compass.config.notification.cache), public: true)
+
+      providers = Compass::Notification::Provider.global_notifications(current_context)
+
+      return unless stale?(providers, etag: "compass-notification")
+
+      render json: providers
+    end
+  end
+end

data/app/controllers/compass/search_controller.rb

@@ -0,0 +1,62 @@
+require "compass/search/provider"
+
+module Compass
+  class SearchController < ApplicationController
+    def index
+      if params[:q]
+        results = Compass::Search::Provider.global_search(params.require(:q), current_context)
+        render json: { results: results }
+      else
+        providers
+      end
+    end
+
+    def show
+      result = Compass::Search::Provider.search(params[:q], params[:provider_name], current_context)
+      render json: {
+        provider: params[:provider_name],
+        context_id: params[:context_id],
+        **result
+      }
+    rescue Compass::Search::UnknownProvider => error
+      render json: {
+        error: error.message,
+        available_providers: error.available_providers
+      }, status: :not_found
+    end
+
+    def providers
+      render json: {
+        context_id: params[:context_id],
+        providers: available_provider_names.map do |name|
+          provider_class = find_provider_by_name(name)
+
+          base_info = {
+            name: name,
+            class_name: provider_class&.name
+          }
+          begin
+            label = provider_class&.new(**current_context)&.label || name.humanize
+            base_info.merge(label: label)
+          rescue => e
+            Rails.logger.warn "Error getting provider info for #{name}: #{e.message}"
+            base_info.merge(
+                label: name.humanize,
+                error: e.message
+            )
+          end
+        end
+      }
+    end
+
+    private
+
+    def find_provider_by_name(name)
+      Compass::Search::Provider.find_by_name(name)
+    end
+
+    def available_provider_names
+      Compass::Search::Provider.available_provider_names
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,12 @@
+Compass::Engine.routes.draw do
+  get ":context_id/menu", to: "menu#index", as: :menu
+
+  get ":context_id/search", to: "search#index", as: :search
+  get ":context_id/search/providers", to: "search#providers", as: :search_providers
+  get ":context_id/search/:provider_name",
+      to: "search#show",
+      as: :search_provider,
+      constraints: { provider_name: /[a-zA-Z_]+/ }
+
+  get ":context_id/notifications", to: "notification#index", as: :notifications
+end

data/lib/compass/breadcrumb/middleware.rb

@@ -0,0 +1,44 @@
+module Compass
+  # Compass breadcrumb handling module.
+  # It leverages the configured breadcrumb strategy to fetch and push breadcrumb items.
+  #
+  module Breadcrumb
+    # Middleware to track breadcrumb items based on requests.
+    # It uses the configured breadcrumb strategy to save breadcrumb items
+    # for requests that should be tracked.
+    #
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @request = ActionDispatch::Request.new(env)
+        context = instance_exec(&Compass.config.context)
+
+        save_breadcrumb!(context) if should_track?(context)
+      rescue => e
+        # Silently handle breadcrumb errors - don't break the request
+        Compass.logger&.error "Breadcrumb middleware error: #{e.message}"
+      ensure
+        return @app.call(env)
+      end
+
+    private
+
+      attr_reader :request
+
+      def save_breadcrumb!(context)
+        ::Compass::Breadcrumb.push(
+          context: context,
+          label: @request.params[:mt],
+          url: @request.url
+        )
+      end
+
+      def should_track?(context)
+        Compass.config.breadcrumb.should_track.call(@request, context)
+      end
+    end
+  end
+end

data/lib/compass/breadcrumb.rb

@@ -0,0 +1,46 @@
+module Compass
+  # Compass breadcrumb handling module.
+  # It leverages the configured breadcrumb strategy to fetch and push breadcrumb items.
+  #
+  module Breadcrumb
+    autoload :Middleware, "compass/breadcrumb/middleware"
+
+    # Fetch breadcrumb for the given context, using the configured strategy.
+    #
+    # I.e.:
+    #
+    #   Compass::Breadcrumb.for(context_id, context: { current_user: }, max: 5)
+    #    => [
+    #      { url: "/home", label: "Home" },
+    #      { url: "/section", label: "Section" },
+    #      { url: "/section/page", label: "Page" }
+    #    ]
+    #
+    # @param context_id [String] The context identifier.
+    # @param context [Hash] The context hash.
+    # @param max [Integer] The maximum number of items to return.
+    # @return [Array<Hash>,nil] The breadcrumb items.
+    def self.for(context: {}, max: 10)
+      Compass.config.breadcrumb.strategy&.for(context: context, max: max)
+    end
+
+    # Push a new breadcrumb item for the given context, using the configured strategy.
+    #
+    # I.e.:
+    #
+    #   Compass::Breadcrumb.push(
+    #     context_id,
+    #     context: { current_user: },
+    #     url: "/section/page",
+    #     label: "Page"
+    #   )
+    #
+    # @param context_id [String] The context identifier.
+    # @param context [Hash] The context hash.
+    # @param url [String] The URL of the breadcrumb item.
+    # @param label [String] The label of the breadcrumb item.
+    def self.push(context: {}, url:, label:)
+      Compass.config.breadcrumb.strategy&.push(context: context, url: url, label: label)
+    end
+  end
+end

data/lib/compass/configuration/breadcrumb.rb

@@ -0,0 +1,24 @@
+module Compass
+  module Configuration::Breadcrumb
+    include ActiveSupport::Configurable
+
+    # Strategy class for breadcrumb functionality.
+    # Applications must provide their own implementation.
+    #
+    # I.e.:
+    #   config.breadcrumb.strategy = MyAppBreadcrumbService
+    #
+    # @see Compass::Breadcrumb for method signatures.
+    #
+    config_accessor :strategy, default: nil
+
+    # Proc to determine if a request should be tracked for breadcrumbs.
+    # It receives the request and context as parameters.
+    #
+    # I.e.:
+    #   config.breadcrumb.should_track = ->(request, context) { request.path != "/login" }
+    #
+    # @return [Proc] The tracking determination proc.
+    config_accessor :should_track, default: ->(request, context) { true }
+  end
+end

data/lib/compass/configuration/menu.rb

@@ -0,0 +1,22 @@
+module Compass
+  # Compass configuration for menu items.
+  module Configuration::Menu
+    include ActiveSupport::Configurable
+
+    # List of menu classes to be autoloaded.
+    #
+    # I.e.: Compass.config.menu.items = %w[ ProjectMenu UserMenu ]
+    config_accessor :items, default: []
+
+    # Cache-Control configuration for menu items.
+    # This configuration is used to set the `Cache-Control` header in the response.
+    # You can set the cache max age in seconds, and other Cache-Control attributes.
+    # The first argument is always the cache max age, either in seconds or in
+    # ActiveSupport::Duration.
+    #
+    # I.e.: Compass.config.menu.cache = 3600
+    # I.e.: Compass.config.menu.cache = [1.hour, public: false]
+    #
+    config_accessor :cache, default: 3600
+  end
+end

data/lib/compass/configuration/notification.rb

@@ -0,0 +1,36 @@
+module Compass
+  module Configuration
+    # Compass configuration for notifications.
+    class Notification
+      include ActiveSupport::Configurable
+
+      # List of notification provider classes to be used.
+      #
+      # Example:
+      #   Compass.config.notification.providers = [UserNotificationProvider, ProjectNotificationProvider]
+      config_accessor :providers, default: []
+
+      # Polling interval for notifications (in seconds).
+      # Can be set to an integer or a lambda returning an integer.
+      #
+      # Example:
+      #   Compass.config.notification.polling_interval = 30
+      config_accessor :polling_interval, default: -> { 30 }
+
+      # Maximum number of notifications to return.
+      #
+      # Example:
+      #   Compass.config.notification.max_notifications = 100
+      config_accessor :max_notifications, default: 100
+
+      # Cache-Control configuration for notifications.
+      # Used to set the `Cache-Control` header in the response.
+      # The first argument is the cache max age (in seconds or ActiveSupport::Duration).
+      #
+      # Example:
+      #   Compass.config.notification.cache = 3600
+      #   Compass.config.notification.cache = [1.hour, public: true]
+      config_accessor :cache, default: 3600
+    end
+  end
+end

data/lib/compass/configuration/search.rb

@@ -0,0 +1,18 @@
+module Compass
+  module Configuration::Search
+    # Compass configuration for search providers and view paths.
+    include ActiveSupport::Configurable
+
+    # List of search provider classes to be used.
+    #
+    # Example:
+    #   Compass.config.search.providers = [CarsSearchProvider, UserSearchProvider]
+    config_accessor :providers, default: []
+
+    # List of view paths for search rendering.
+    #
+    # Example:
+    #   Compass.config.search.view_paths = ["app/views/search"]
+    config_accessor :view_paths, default: []
+  end
+end

data/lib/compass/configuration.rb

@@ -0,0 +1,45 @@
+require "active_support/configurable"
+
+# Compass configuration
+module Compass
+  # Configuration options for Compass.
+  #
+  # To configure, use the `configure` method. For example:
+  #
+  #  Compass.configure do |config|
+  #   config.authenticate = -> do
+  #     authenticate_or_request_with_http_token do |token, options|
+  #       @current_user = User.find_by(token: token)
+  #     end
+  #   end
+  #   config.context = -> { { current_user: } }
+  #   config.etag = -> { current_user.id }
+  #
+  #   # Configure menu
+  #   config.menu.items = %w[ TestMenu ]
+  #   config.menu.cache = 3600
+  #  end
+  #
+  module Configuration
+    extend ::ActiveSupport::Concern
+
+    autoload :Menu, "compass/configuration/menu"
+    autoload :Search, "compass/configuration/search"
+    autoload :Notification, "compass/configuration/notification"
+    autoload :Breadcrumb, "compass/configuration/breadcrumb"
+
+    included do
+      include ActiveSupport::Configurable
+
+      config_accessor :authenticate, default: -> { false }
+      config_accessor :context, default: -> { {} }
+      config_accessor :context_id, default: -> { }
+      config_accessor :modified_at, default: -> { }
+
+      config_accessor :menu, default: Compass::Configuration::Menu
+      config_accessor :search, default: Compass::Configuration::Search
+      config_accessor :notification, default: Compass::Configuration::Notification
+      config_accessor :breadcrumb, default: Compass::Configuration::Breadcrumb
+    end
+  end
+end

data/lib/compass/engine.rb

@@ -0,0 +1,27 @@
+require "compass"
+
+module Compass
+  # Rails plugin to autoload compass features such as Menu.
+  # Mounting this engine exposes the routes necessary to allow other apps
+  # to integrate with this Rails application. See more in `config/routes.rb`.
+  #
+  class Engine < ::Rails::Engine
+    isolate_namespace Compass
+    config.generators.api_only = true
+    config.compass = Compass.config
+
+    initializer "compass.logger" do
+      Compass.logger ||= Rails.logger.respond_to?(:tagged) ? Rails.logger.tagged("Compass") : Rails.logger
+    end
+
+    initializer "compass.search.view_paths", after: "action_controller.set_configs" do |app|
+      ActiveSupport.on_load(:action_controller) do
+        Compass.config.search.view_paths = ActionController::Base.view_paths
+      end
+    end
+
+    initializer "compass.middleware" do |app|
+      app.middleware.use Compass::Breadcrumb::Middleware
+    end
+  end
+end

data/lib/compass/lazy_attribute.rb

@@ -0,0 +1,55 @@
+module Compass
+  # Allows a Ruby class to define an attribute, that relies on another
+  # attribute to evaluate a value.
+  # @private
+  module LazyAttribute
+    # A lazy evaluated value, evaluated in the given context when required.
+    #
+    # @private
+    class LazyValue
+      def initialize(ctx, value)
+        @ctx = ctx
+        @value = value
+      end
+
+      def get
+        case @value
+        when Symbol then @ctx.send(@value)
+        when Proc then @ctx.instance_exec(&@value)
+        else @value
+        end
+      end
+    end
+
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Defines a lazy_attribute, which can be set to a block or a symbol to be
+      # lazily evaluated within the context of the given attribute.
+      #
+      # I.e.:
+      #
+      #  class Car < Struct.new(:engine)
+      #    lazy_attribute :power, :engine
+      #  end
+      #  StrongEngine = Struct.new(:cylinder)
+      #
+      #  car = Car.new(StrongEngine.new(2000))
+      #  car.power(:cylinder)
+      #  car.power => 2000
+      #
+      def lazy_attribute(name, ctxmth, &getter)
+        define_method(name) do |value = nil, &block|
+          context = send(ctxmth)
+          if value.present? || block.present?
+            instance_variable_set("@#{name}", LazyValue.new(context, value || block))
+          else
+            lazy_value = instance_variable_get("@#{name}")
+            value = lazy_value ? lazy_value.get : context.respond_to?(name) ? context.send(name) : nil
+            instance_exec(value, &(getter || :itself))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/compass/menu/item.rb

@@ -0,0 +1,91 @@
+module Compass
+  # It is an item builder class. It leverages Compass::LazyAttribute to be able
+  # to build its attributes based on a menu context, allowing shared methods to
+  # live in the Menu class.
+  #
+  class Menu::Item
+    attr_reader :items, :menu
+
+    include LazyAttribute
+
+    def initialize(menu, &block)
+      @menu = menu
+      @items = Menu::ItemList.new
+
+      instance_exec(menu, &block)
+    end
+
+    # Item gravity. This is used to sort items in the menu.
+    # The default gravity is 1, so if an item should always float to the top,
+    # the gravity should be set to 0.#
+    lazy_attribute(:gravity, :menu) do |gravity|
+      gravity.presence || 1
+    end
+    # Shallowness of the item. If the item is shallow, it will not be rendered,
+    # meaning that its children will be rendered in its place.
+    lazy_attribute :shallow, :menu
+    # Item label. This is the text that will be displayed in the menu.
+    lazy_attribute :label, :menu
+    # Item URL. This is the URL that the item will link to.
+    lazy_attribute :url, :menu
+    # Item icon. This is the icon that will be displayed in the menu.
+    lazy_attribute :icon, :menu
+    # Item meta data is used for various things, usually tied to the UI behavior.
+    # For example, to tell the UI that this item should be rendered in full screen
+    # meta could be set to `meta { full_screen true }`.
+    lazy_attribute :meta, :menu
+    # Badge count. This is the number that will be displayed in the badge when above 0.
+    lazy_attribute :badge_count, :menu do |count|
+      count.to_i + items.sum(&:badge_count)
+    end
+    # Authorizes the current context to render the item.
+    # I.e.: authorized { current_user.admin? }
+    lazy_attribute :authorized, :menu do |authorized|
+      authorized || authorized.nil?
+    end
+    # The last time anything about this item in this context was changed, including the authorization.
+    lazy_attribute :updated_at, :menu do |updated_at|
+      [ self.items.maximum(:updated_at), updated_at ].compact.max
+    end
+    # Tags that are associated with the item. This is used to filter items.
+    lazy_attribute :tags, :menu do |tags|
+      [ *self.items.flat_map(&:tags), *tags ]
+    end
+
+    # Nest items under the current item.
+    #
+    # I.e.:
+    #  item do
+    #    label "Users"
+    #    item do
+    #      label "Profile"
+    #      url :profile_url
+    #    end
+    #  end
+    #
+    def item(&block)
+      Menu::Item.new(@menu, &block).tap do |item|
+        self.items.push(item)
+      end
+    end
+
+    # @private
+    def each(&block)
+      return yield self unless shallow
+
+      items.each(&block)
+    end
+
+    def as_json(options = {})
+      {
+        label: label,
+        icon: icon,
+        url: url,
+        items: items,
+        badge: badge_count.nonzero?,
+        meta: meta,
+        gravity: gravity
+      }.as_json(options).compact_blank
+    end
+  end
+end

data/lib/compass/menu/item_list.rb

@@ -0,0 +1,57 @@
+module Compass
+  # It is a list of Compass::Menu::Item, which can be filtered and
+  # represented as_json recursivelly throuhout the entire tree.
+  #
+  # @private
+  class Menu::ItemList
+    include Enumerable
+
+    def initialize(items = [])
+      @items = items
+    end
+
+    def push(...)
+      @items.push(...)
+    end
+
+    def each(&block)
+      @items.each do |item|
+        item.each(&block)
+      end
+    end
+
+    def as_json(options = {})
+      filter(**options.fetch(:filter, {})).to_a.as_json(options)
+    end
+
+    def filter(**filters)
+      filters.reduce(self) do |items, (filter, arg)|
+        arg ? items.public_send(filter, arg) : items
+      end
+    end
+
+    def maximum(attr)
+      filter_map(&attr).max
+    end
+
+    def select(&block)
+      self.class.new(super(&block))
+    end
+
+    def authorized(*)
+      select(&:authorized)
+    end
+
+    def tagged(tag)
+      select { |item| item.tags&.include?(tag) }
+    end
+
+    def sort(attrs)
+      attrs = Array(attrs)
+      sorted = sort_by do |item|
+        attrs.map { |attr| item.public_send(attr) }
+      end
+      self.class.new(sorted)
+    end
+  end
+end

data/lib/compass/menu.rb

@@ -0,0 +1,117 @@
+module Compass
+  # Compass::Menu is the base class for exposing menus from a Compass enabled application.
+  # This class acts as a builder for the menu items. Each root menu should extend this
+  # class to build a menu tree.
+  #
+  # I.e.:
+  #
+  #   class UserMenu < Compass::Menu
+  #     include Rails.application.routes.mounted_helpers
+  #
+  #     item do
+  #       label "Users"
+  #
+  #       item do
+  #         label "Profile"
+  #         url :profile_url
+  #       end
+  #
+  #       item do
+  #         label "Settings"
+  #         url :user_settings_url
+  #       end
+  #     end
+  #   end
+  #
+  # In most cases an application will expose multiple menus, and so an Application level
+  # base class should be created:
+  #
+  # I.e.:
+  #
+  #   class ApplicationMenu < Compass::Menu
+  #     include Rails.application.routes.mounted_helpers
+  #   end
+  #
+  #   class UserMenu < ApplicationMenu
+  #     item do
+  #       label "Users"
+  #
+  #       item do
+  #         label "Profile"
+  #         url :profile_url
+  #       end
+  #
+  #       item do
+  #         label "Settings"
+  #         url :user_settings_url
+  #       end
+  #     end
+  #   end
+  #
+  # @see Compass::Menu::Item
+  class Menu
+    autoload :Item, "compass/menu/item"
+    autoload :ItemList, "compass/menu/item_list"
+
+    # Allow building a menu from a list of items.
+    # This is useful for building a menu from a list of items
+    # with the given context.
+    #
+    # I.e.:
+    #  Compass::Menu.build(["UserMenu", "AdminMenu"], current_user: user)
+    #
+    # By default, it will build items from `Compass.menus`.
+    #
+    # I.e.:
+    #  Compass.config.menu.items = ["UserMenu", "AdminMenu"]
+    #  Compass::Menu.build(current_user: user)
+    #
+    # @param items [Array<String>] the list of menu items to build
+    # @param context [Hash] the context to pass to the menu items
+    # @return [ItemList] the list of menu items
+    def self.build(items = Compass.config.menu.items, **context)
+      Array(items).map(&:constantize)
+                  .map { _1.new(**context).build }
+                  .then(&ItemList.method(:new))
+    end
+
+    # Define the root item of the menu.
+    # This method should be called in the class definition to define the root item
+    # of the menu.
+    #
+    # I.e.:
+    #  class UserMenu < Compass::Menu
+    #    item do
+    #      label "Users"
+    #
+    #      item do
+    #        label "Profile"
+    #        url :profile_url
+    #      end
+    #    end
+    #  end
+    #
+    # @yield the block to define the root item
+    def self.item(&block)
+      define_method(:build) do
+        @item ||= Item.new(self, &block)
+      end
+    end
+
+    # Initialize the menu with the given context.
+    # Each context key will be available as a method on the instance.
+    # Because items are built from the context, they will have access
+    # to these context methods
+    #
+    # I.e.:
+    #  menu = UserMenu.new(current_user: user)
+    #  menu.current_user # => user
+    #
+    # @param context [Hash] the context to pass to the menu items
+    def initialize(**context)
+      context.each do |key, value|
+        define_singleton_method(key) { value }
+      end
+    end
+  end
+end

data/lib/compass/notification/provider.rb

@@ -0,0 +1,73 @@
+module Compass
+  module Notification
+    class UnknownProvider < StandardError
+      attr_reader :provider_name, :available_providers
+
+      def initialize(provider_name, available_providers)
+        @provider_name = provider_name
+        @available_providers = available_providers
+        super("Notification provider '#{provider_name}' not found")
+      end
+    end
+
+    class Provider
+      class << self
+        def global_notifications(context = {})
+          Compass.config.notification.providers.map do |provider|
+            begin
+              provider_class = provider.try(:constantize) || provider
+              provider_class.new(**context)
+            rescue => e
+              Compass.logger&.error("[ Compass::Notification::Provider ] #{provider}: #{e.class}: #{e.message}")
+              nil
+            end
+          end
+        end
+      end
+
+      # Instance methods
+      def initialize(**context)
+        @context = context
+        context.each { |key, value| define_singleton_method(key) { value } }
+      end
+
+      def fetch_notifications
+        retrieve_notifications
+      rescue => e
+        log_error(e)
+        []
+      end
+
+      def retrieve_notifications
+        raise NotImplementedError, "#{self.class} must implement #retrieve_notifications"
+      end
+
+      def format_notification(notification)
+        raise NotImplementedError, "#{self.class} must implement #format_notification"
+      end
+
+      def label
+        raise NotImplementedError, "#{self.class} must implement #label"
+      end
+
+      def updated_at
+        raise NotImplementedError, "#{self.class} must implement #updated_at"
+      end
+
+      def as_json(options = {})
+        {
+          label: label,
+          notifications: Array(fetch_notifications).map { |notification| format_notification(notification) }.compact
+        }
+      end
+
+      private
+
+      def log_error(error)
+        Compass.logger&.error(
+          "[ Compass::Notification::Provider ] #{self.class}: #{error.class}: #{error.message}"
+        )
+      end
+    end
+  end
+end

data/lib/compass/notification.rb

@@ -0,0 +1,5 @@
+module Compass
+  module Notification
+    autoload :Provider, "compass/notification/provider"
+  end
+end

data/lib/compass/rspec/menu.rb

@@ -0,0 +1,108 @@
+module Compass
+  # Compass::Menu test helper for RSpec
+  module Rspec::Menu
+    # Creates a matcher for menu items, allowing you to assert that a menu item
+    # with a given label exists.
+    #
+    # I.e.:
+    #  menu = ExampleMenu.new
+    #
+    #  expect(menu).to have_menu_item("Dashboard")
+    #  expect(menu).to have_menu_item("Dashboard").with_url("/dashboard")
+    #  expect(menu).to have_menu_item("Dashboard").with_icon("fa fa-dashboard")
+    #  expect(menu).to have_menu_item("Dashboard").with_tags("tag1", "tag2")
+    #  expect(menu).to have_menu_item("Dashboard").with_badge(1)
+    #  expect(menu).to(
+    #    have_menu_item("Dashboard")
+    #      .with_badge(1)
+    #      .with_icon("dashboard")
+    #  )
+    #
+    #
+    # The matcher will test whether the given menu/item has a
+    # nested authorized item with the given attributes.
+    # To match unauthorized items, you can also pass `authorized: false`
+    # to `have_menu_item`.
+    #
+    # I.e.:
+    #
+    #  menu = ExampleMenu.new
+    #  expect(menu).to have_menu_item("Unauthorized Item", authorized: false)
+    #
+    # @param label [String] the label of the menu item
+    # @param url [String] the URL of the menu item
+    # @param badge [String] the badge of the menu item
+    # @param icon [String] the icon of the menu item
+    # @param tags [Array<String>] the tags of the menu item
+    # @param authorized [Boolean] whether the menu item is authorized
+    # @return [HaveMenuItem] the matcher
+    def have_menu_item(...) # rubocop:disable Naming/PredicateName
+      HaveMenuItem.new(...)
+    end
+
+    class HaveMenuItem
+      def initialize(label, url: nil, badge: nil, icon: nil, tags: nil, authorized: true)
+        @label = label
+        @attributes = {
+          url: url,
+          authorized: authorized,
+          badge: badge,
+          icon: icon,
+          tags: tags
+        }
+      end
+
+      def matches?(menu_item)
+        @menu_item = menu_item
+        matching_label = menu_item.items.find do |item|
+          item.label == @label
+        end
+        if matching_label
+          @matcher = RSpec::Matchers::BuiltIn::HaveAttributes.new(@attributes.compact)
+          def @matcher.actual_formatted = @actual.label.inspect
+          @matcher.matches?(matching_label)
+        else
+          false
+        end
+      end
+
+      # Matches the item URL
+      def with_url(url)
+        @attributes[:url] = url
+        self
+      end
+
+      # Matches the item icon
+      def with_icon(icon)
+        @attributes[:icon] = icon
+        self
+      end
+
+      # Matches the item tags
+      def with_tags(*tags)
+        @attributes[:tags] = tags.flatten
+        self
+      end
+
+      # Matches the item badge
+      def with_badge(badge)
+        @attributes[:badge] = badge
+        self
+      end
+
+      # @private
+      def failure_message
+        return @matcher.failure_message if @matcher
+
+        "expected #{@menu_item.label} to have nested item #{@label}"
+      end
+
+      # @private
+      def failure_message_when_negated
+        return @matcher.failure_message_when_negated if @matcher
+
+        "expected #{@menu_item.label} to not have nested item #{@label}"
+      end
+    end
+  end
+end

data/lib/compass/rspec.rb

@@ -0,0 +1,5 @@
+module Compass
+  module Rspec
+    autoload :Menu, "compass/rspec/menu"
+  end
+end

data/lib/compass/search/provider.rb

@@ -0,0 +1,118 @@
+module Compass
+  module Search
+    class UnknownProvider < StandardError
+      attr_reader :provider_name, :available_providers
+
+      def initialize(provider_name, available_providers)
+        @provider_name = provider_name
+        @available_providers = available_providers
+        super("Provider '#{provider_name}' not found")
+      end
+    end
+
+    class Provider
+      include Compass::Search::Rendering
+
+      class << self
+        attr_reader :providers
+
+        # Handles both class objects and string class names
+        def constantize_provider(provider)
+          provider.is_a?(String) ? provider.constantize : provider
+        end
+
+        # Aggregates search results from all registered providers
+        def global_search(query, context = {})
+          Compass.config.search.providers.flat_map do |provider|
+            begin
+              provider_class = constantize_provider(provider)
+              provider_class.new(**context).search(query)
+            rescue => e
+              Compass.logger&.error("[ Compass::Search::Provider ] #{provider_class}: #{e.class}: #{e.message}")
+              []
+            end
+          end
+        end
+
+        # Add this new class method for individual provider search
+        def search(query, provider_name, context = {})
+          provider_class = find_by_name(provider_name)
+          if provider_class
+            provider_class.new(**context).search(query)
+          else
+            raise UnknownProvider.new(provider_name, available_provider_names)
+          end
+        end
+
+        def normalize_name(provider_class)
+          provider_class.name.demodulize.underscore.sub(/_?provider$/, "")
+        end
+
+        def find_by_name(name)
+          Compass.config.search.providers.find do |provider|
+            provider_class = constantize_provider(provider)
+            normalize_name(provider_class) == name.to_s
+          end&.then { |p| constantize_provider(p) }
+        end
+
+        def available_provider_names
+          Compass.config.search.providers.map do |provider|
+            provider_class = constantize_provider(provider)
+            normalize_name(provider_class)
+          end
+        end
+      end
+
+      def initialize(**context)
+        @context = context
+        context.each { |key, value| define_singleton_method(key) { value } }
+      end
+
+      def search(query)
+        records = fetch_records(query)
+        {
+          label: label,
+          search_options: search_options,
+          results: Array(records).map { |record| format_result(record) }.compact
+        }
+      rescue => e
+        log_error(e, query)
+        {
+          label: label,
+          search_options: search_options,
+          results: []
+        }
+      end
+
+      def label
+        self.class.name.demodulize.sub(/Provider$/, "").titleize
+      end
+
+      def search_options
+        {
+          keys: [ { name: "label", weight: 1 } ],
+          threshold: 0.2
+        }
+      end
+
+      def fetch_records(query)
+        raise NotImplementedError, "#{self.class} must implement #fetch_records"
+      end
+
+      def format_result(record)
+        {
+          id: record.try(:id),
+          label: record.try(:label) || record.try(:name) || record.try(:title) || record.try(:to_s),
+          category: record.try(:category) || record.class.name.demodulize,
+          tag: record.try(:tag) || record.try(:role)
+        }.compact
+      end
+
+      def log_error(error, query)
+         Compass.logger&.error(
+          "[ Compass::Search::Provider ] #{self.class}: #{error.class}: #{error.message} | Query: #{query.inspect}"
+        )
+      end
+    end
+  end
+end

data/lib/compass/search/rendering.rb

@@ -0,0 +1,27 @@
+module Compass
+  module Search
+    module Rendering
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :helpers, default: []
+      end
+
+      class_methods do
+        def helper(*mods)
+          self.helpers += mods
+        end
+      end
+
+      def view_context
+        @view_context ||= ViewContext.new.tap do |ctx|
+          self.class.helpers.each { |mod| ctx.extend(mod) }
+        end
+      end
+
+      def render(partial, locals = {})
+        view_context.render(partial: partial, locals: { **@context, **locals })
+      end
+    end
+  end
+end

data/lib/compass/search/view_context.rb

@@ -0,0 +1,22 @@
+module Compass
+  module Search
+    class ViewContext < ActionView::Base
+      def initialize(view_paths = [])
+        all_view_paths = Compass.config.search.view_paths + Array(view_paths)
+        super ActionView::LookupContext.new(all_view_paths), {}, nil
+      end
+
+      def view_paths
+        Compass.config.search.view_paths
+      end
+
+      def compiled_method_container
+        self.class.compiled_method_container
+      end
+
+      def self.compiled_method_container
+        self
+      end
+    end
+  end
+end

data/lib/compass/search.rb

@@ -0,0 +1,7 @@
+module Compass
+  module Search
+    autoload :Rendering, "compass/search/rendering"
+    autoload :Provider, "compass/search/provider"
+    autoload :ViewContext, "compass/search/view_context"
+  end
+end

data/lib/compass/version.rb

@@ -0,0 +1,3 @@
+module Compass
+  VERSION = "0.1.0"
+end

data/lib/compass.rb

@@ -0,0 +1,19 @@
+require "compass/configuration"
+require "compass/version"
+
+# Compass implements the Compass communication protocol, allowing apps
+# to integrate to a Compass ecossystem, exposing Menu, Search, and other
+# features.
+module Compass
+  class << self
+    attr_accessor :logger
+  end
+
+  autoload :Menu, "compass/menu"
+  autoload :Search, "compass/search"
+  autoload :Notification, "compass/notification"
+  autoload :Breadcrumb, "compass/breadcrumb"
+  autoload :LazyAttribute, "compass/lazy_attribute"
+
+  include Compass::Configuration
+end

data/lib/tasks/compass_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :compass do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: power-compass
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carlos Palhares
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Compass provides backend services for Compass:UI
+email:
+- chjunior@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/compass/application_controller.rb
+- app/controllers/compass/menu_controller.rb
+- app/controllers/compass/notification_controller.rb
+- app/controllers/compass/search_controller.rb
+- config/routes.rb
+- lib/compass.rb
+- lib/compass/breadcrumb.rb
+- lib/compass/breadcrumb/middleware.rb
+- lib/compass/configuration.rb
+- lib/compass/configuration/breadcrumb.rb
+- lib/compass/configuration/menu.rb
+- lib/compass/configuration/notification.rb
+- lib/compass/configuration/search.rb
+- lib/compass/engine.rb
+- lib/compass/lazy_attribute.rb
+- lib/compass/menu.rb
+- lib/compass/menu/item.rb
+- lib/compass/menu/item_list.rb
+- lib/compass/notification.rb
+- lib/compass/notification/provider.rb
+- lib/compass/rspec.rb
+- lib/compass/rspec/menu.rb
+- lib/compass/search.rb
+- lib/compass/search/provider.rb
+- lib/compass/search/rendering.rb
+- lib/compass/search/view_context.rb
+- lib/compass/version.rb
+- lib/tasks/compass_tasks.rake
+homepage: https://powerhrg.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://powerhrg.com
+  source_code_uri: https://powerhrg.com
+  changelog_uri: https://powerhrg.com
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Compass provides backend services for Compass:UI
+test_files: []