phlexi-menu 0.0.3 → 0.2.0

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    phlexi-menu (0.0.1)
+    phlexi-menu (0.2.0)
       phlex (~> 1.11)
       phlexi-field
       zeitwerk

data/lib/phlexi/menu/badge.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "phlex"
+
+module Phlexi
+  module Menu
+    # A component for rendering badge elements in menus
+    #
+    # @example Basic usage
+    #   Badge.new("New!", class: "badge-primary")
+    #
+    # @example With custom styling
+    #   Badge.new("2", class: "badge-notification")
+    #
+    class Badge < COMPONENT_BASE
+      # Initialize a new badge component
+      #
+      # @param content [String] The text content to display in the badge
+      # @param options [Hash] Additional HTML attributes for the badge element
+      # @option options [String] :class CSS classes to apply to the badge
+      def initialize(content, **options)
+        @content = content
+        @options = options
+        super()
+      end
+
+      def view_template
+        span(class: @options[:class]) { @content }
+      end
+    end
+  end
+end

data/lib/phlexi/menu/builder.rb

@@ -47,27 +47,6 @@ module Phlexi
         new_item
       end
 
-      # Checks if the menu has any items.
-      #
-      # @return [Boolean] true if the menu has no items, false otherwise
-      def empty?
-        @items.empty?
-      end
-
-      # Returns the number of top-level items in the menu.
-      #
-      # @return [Integer] The count of top-level menu items
-      def size
-        @items.size
-      end
-
-      # Checks if this menu item has any nested items.
-      #
-      # @return [Boolean] true if the item has nested items, false otherwise
-      def nested?
-        !empty?
-      end
-
       # Returns a string representation of the menu structure.
       #
       # @return [String] A human-readable representation of the menu

data/lib/phlexi/menu/component.rb

@@ -14,7 +14,7 @@ module Phlexi
     #       def self.theme
     #         super.merge({
     #           nav: "bg-white shadow",
-    #           item_label: "text-gray-600"
+    #           item_label: ->(depth) { "text-gray-#{600 + (depth * 100)}" }
     #         })
     #       end
     #     end
@@ -23,6 +23,8 @@ module Phlexi
       # Theme class for customizing menu appearance
       class Theme < Phlexi::Menu::Theme; end
 
+      class Badge < Phlexi::Menu::Badge; end
+
       # @return [Integer] The default maximum nesting depth for menu items
       DEFAULT_MAX_DEPTH = 3
 
@@ -31,20 +33,18 @@ module Phlexi
       # @param menu [Phlexi::Menu::Builder] The menu structure to render
       # @param max_depth [Integer] Maximum nesting depth for menu items
       # @param options [Hash] Additional options passed to rendering methods
+      # @raise [ArgumentError] If menu is nil
       def initialize(menu, max_depth: default_max_depth, **options)
+        raise ArgumentError, "Menu cannot be nil" if menu.nil?
+
         @menu = menu
         @max_depth = max_depth
         @options = options
         super()
       end
 
-      # Renders the menu structure as HTML.
-      #
-      # @return [String] The rendered HTML
       def view_template
-        nav(class: themed(:nav)) do
-          render_items(@menu.items)
-        end
+        nav(class: themed(:nav)) { render_items(@menu.items) }
       end
 
       protected
@@ -53,14 +53,12 @@ module Phlexi
       #
       # @param items [Array<Phlexi::Menu::Item>] The items to render
       # @param depth [Integer] Current nesting depth
+      # @return [void]
       def render_items(items, depth = 0)
-        return if depth >= @max_depth
-        return if items.empty?
+        return if depth >= @max_depth || items.empty?
 
-        ul(class: themed(:items_container)) do
-          items.each do |item|
-            render_item_wrapper(item, depth)
-          end
+        ul(class: themed(:items_container, depth)) do
+          items.each { |item| render_item_wrapper(item, depth) }
         end
       end
 
@@ -68,116 +66,197 @@ module Phlexi
       #
       # @param item [Phlexi::Menu::Item] The item to wrap
       # @param depth [Integer] Current nesting depth
+      # @return [void]
       def render_item_wrapper(item, depth)
-        li(class: tokens(
-          themed(:item_wrapper),
-          active_class(item),
-          item_parent_class(item)
-        )) do
-          render_item_content(item)
-          render_items(item.items, depth + 1) if item.items.any?
+        li(class: compute_item_wrapper_classes(item, depth)) do
+          render_item_content(item, depth)
+          render_nested_items(item, depth)
         end
       end
 
+      # Computes CSS classes for item wrapper
+      #
+      # @param item [Phlexi::Menu::Item] The menu item
+      # @param depth [Integer] Current nesting depth
+      # @return [String] Space-separated CSS classes
+      def compute_item_wrapper_classes(item, depth)
+        tokens(
+          themed(:item_wrapper, depth),
+          item_parent_class(item, depth),
+          active?(item) ? themed(:active, depth) : nil
+        )
+      end
+
+      # Renders nested items if present and within depth limit
+      #
+      # @param item [Phlexi::Menu::Item] The parent menu item
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_nested_items(item, depth)
+        render_items(item.items, depth + 1) if nested?(item, depth)
+      end
+
       # Renders the content of a menu item, choosing between link and span.
       #
       # @param item [Phlexi::Menu::Item] The item to render content for
-      def render_item_content(item)
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_item_content(item, depth)
         if item.url
-          render_item_link(item)
+          render_item_link(item, depth)
         else
-          render_item_span(item)
+          render_item_span(item, depth)
         end
       end
 
       # Renders a menu item as a link.
       #
       # @param item [Phlexi::Menu::Item] The item to render as a link
-      def render_item_link(item)
-        a(href: item.url, class: themed(:item_link)) do
-          render_item_interior(item)
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_item_link(item, depth)
+        a(
+          href: item.url,
+          class: tokens(themed(:item_link, depth), active_class(item, depth))
+        ) do
+          render_item_interior(item, depth)
         end
       end
 
       # Renders a menu item as a span (for non-linking items).
       #
       # @param item [Phlexi::Menu::Item] The item to render as a span
-      def render_item_span(item)
-        span(class: themed(:item_span)) do
-          render_item_interior(item)
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_item_span(item, depth)
+        span(class: themed(:item_span, depth)) do
+          render_item_interior(item, depth)
         end
       end
 
       # Renders the interior content of a menu item (badges, icon, label).
       #
       # @param item [Phlexi::Menu::Item] The item to render interior content for
-      def render_item_interior(item)
-        render_leading_badge(item.leading_badge) if item.leading_badge
-        render_icon(item.icon) if item.icon
-        render_label(item.label)
-        render_trailing_badge(item.trailing_badge) if item.trailing_badge
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_item_interior(item, depth)
+        render_leading_badge(item, depth) if item.leading_badge
+        render_icon(item.icon, depth) if item.icon
+        render_label(item.label, depth)
+        render_trailing_badge(item, depth) if item.trailing_badge
       end
 
       # Renders the item's label.
       #
       # @param label [String, Component] The label to render
-      def render_label(label)
-        phlexi_render(label) {
-          span(class: themed(:item_label)) { label }
-        }
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_label(label, depth)
+        phlexi_render(label) do
+          span(class: themed(:item_label, depth)) { label }
+        end
+      end
+
+      # Renders the leading badge if present
+      #
+      # @param item [Phlexi::Menu::Item] The menu item
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_leading_badge(item, depth)
+        return unless item.leading_badge
+
+        div(class: themed(:leading_badge_wrapper, depth)) do
+          render_badge(item.leading_badge, item.leading_badge_options, :leading_badge, depth)
+        end
       end
 
-      # Renders the item's leading badge.
+      # Renders the trailing badge if present
       #
-      # @param badge [String, Component] The leading badge to render
-      def render_leading_badge(badge)
-        phlexi_render(badge) {
-          span(class: themed(:leading_badge)) { badge }
-        }
+      # @param item [Phlexi::Menu::Item] The menu item
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_trailing_badge(item, depth)
+        return unless item.trailing_badge
+
+        div(class: themed(:trailing_badge_wrapper, depth)) do
+          render_badge(item.trailing_badge, item.trailing_badge_options, :trailing_badge, depth)
+        end
       end
 
-      # Renders the item's trailing badge.
+      # Renders a badge with given options
       #
-      # @param badge [String, Component] The trailing badge to render
-      def render_trailing_badge(badge)
-        phlexi_render(badge) {
-          span(class: themed(:trailing_badge)) { badge }
-        }
+      # @param badge [Object] The badge content
+      # @param options [Hash] Badge rendering options
+      # @param type [Symbol] Badge type (leading or trailing)
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_badge(badge, options, type, depth)
+        phlexi_render(badge) do
+          render self.class::Badge.new(badge, **options)
+        end
       end
 
       # Renders the item's icon.
       #
       # @param icon [Class] The icon component class to render
-      def render_icon(icon)
+      # @param depth [Integer] Current nesting depth
+      # @return [void]
+      def render_icon(icon, depth)
         return unless icon
 
-        div(class: themed(:icon_wrapper)) do
-          render icon.new(class: themed(:icon))
+        div(class: themed(:icon_wrapper, depth)) do
+          render icon.new(class: themed(:icon, depth))
         end
       end
 
       # Determines the active state class for an item.
       #
       # @param item [Phlexi::Menu::Item] The item to check active state for
+      # @param depth [Integer] Current nesting depth
       # @return [String, nil] The active class name or nil
-      def active_class(item)
-        item.active?(self) ? themed(:active) : nil
+      def active_class(item, depth)
+        active?(item) ? themed(:active, depth) : nil
+      end
+
+      # Helper method to check if an item is active
+      #
+      # @param item [Phlexi::Menu::Item] The item to check
+      # @return [Boolean] Whether the item is active
+      def active?(item)
+        item.active?(self)
+      end
+
+      # Determines if an item should be treated as nested based on its contents
+      # and the current depth relative to the maximum allowed depth.
+      #
+      # @param item [Phlexi::Menu::Item] The item to check
+      # @param depth [Integer] Current nesting depth
+      # @return [Boolean] Whether the item should be treated as nested
+      def nested?(item, depth)
+        has_children = item.items.any?
+        within_depth = (depth + 1) < @max_depth
+        has_children && within_depth
       end
 
       # Determines the parent state class for an item.
       #
       # @param item [Phlexi::Menu::Item] The item to check parent state for
+      # @param depth [Integer] Current nesting depth
       # @return [String, nil] The parent class name or nil
-      def item_parent_class(item)
-        item.items.any? ? themed(:item_parent) : nil
+      def item_parent_class(item, depth)
+        nested?(item, depth) ? themed(:item_parent, depth) : nil
       end
 
       # Resolves a theme component to its CSS classes.
       #
       # @param component [Symbol] The theme component to resolve
+      # @param depth [Integer] Current nesting depth
       # @return [String, nil] The resolved CSS classes or nil
-      def themed(component)
-        self.class::Theme.instance.resolve_theme(component)
+      def themed(component, depth = 0)
+        theme = self.class::Theme.instance.resolve_theme(component)
+        return nil if theme.nil?
+        return theme unless theme.respond_to?(:call)
+        theme.call(depth)
       end
 
       # Renders either a component or simple value with fallback.
@@ -185,6 +264,7 @@ module Phlexi
       # @param arg [Object] The value to render
       # @yield The default rendering block
       # @raise [ArgumentError] If no block is provided
+      # @return [void]
       def phlexi_render(arg, &)
         return unless arg
         raise ArgumentError, "phlexi_render requires a default render block" unless block_given?
@@ -198,6 +278,7 @@ module Phlexi
         end
       end
 
+      # @return [Integer] The default maximum depth for the menu
       def default_max_depth = self.class::DEFAULT_MAX_DEPTH
     end
   end

data/lib/phlexi/menu/item.rb

@@ -20,6 +20,11 @@ module Phlexi
     #     admin.item "Users", url: "/admin/users"
     #     admin.item "Settings", url: "/admin/settings"
     #   end
+    #
+    # @example Custom active state logic
+    #   Item.new("Dashboard", url: "/dashboard", active: -> (context) {
+    #     context.controller.controller_name == "dashboards"
+    #   })
     class Item
       # @return [String] The display text for the menu item
       attr_reader :label
@@ -33,9 +38,15 @@ module Phlexi
       # @return [String, Component, nil] The badge displayed before the label
       attr_reader :leading_badge
 
+      # @return [Hash] Options for the leading badge
+      attr_reader :leading_badge_options
+
       # @return [String, Component, nil] The badge displayed after the label
       attr_reader :trailing_badge
 
+      # @return [Hash] Options for the trailing badge
+      attr_reader :trailing_badge_options
+
       # @return [Array<Item>] Collection of nested menu items
       attr_reader :items
 
@@ -55,14 +66,12 @@ module Phlexi
       # @raise [ArgumentError] If the label is nil or empty
       def initialize(label, url: nil, icon: nil, leading_badge: nil, trailing_badge: nil, **options, &)
         raise ArgumentError, "Label cannot be nil" unless label
-
         @label = label
         @url = url
         @icon = icon
-        @leading_badge = leading_badge
-        @trailing_badge = trailing_badge
-        @options = options
         @items = []
+        @options = options
+        setup_badges(leading_badge, trailing_badge, options)
 
         yield self if block_given?
       end
@@ -70,16 +79,44 @@ module Phlexi
       # Creates and adds a nested menu item.
       #
       # @param label [String] The display text for the nested item
-      # @param ** [Hash] Additional options passed to the Item constructor
+      # @param args [Hash] Additional options passed to the Item constructor
       # @yield [item] Optional block for adding further nested items
       # @yieldparam item [Item] The newly created nested item
       # @return [Item] The created nested item
-      def item(label, **, &)
-        new_item = self.class.new(label, **, &)
+      def item(label, **args, &)
+        new_item = self.class.new(label, **args, &)
         @items << new_item
         new_item
       end
 
+      # Add a leading badge to the menu item
+      #
+      # @param badge [String, Component] The badge content
+      # @param opts [Hash] Additional options for the badge
+      # @return [self] Returns self for method chaining
+      # @raise [ArgumentError] If badge is nil
+      def with_leading_badge(badge, **opts)
+        raise ArgumentError, "Badge cannot be nil" if badge.nil?
+
+        @leading_badge = badge
+        @leading_badge_options = opts.freeze
+        self
+      end
+
+      # Add a trailing badge to the menu item
+      #
+      # @param badge [String, Component] The badge content
+      # @param opts [Hash] Additional options for the badge
+      # @return [self] Returns self for method chaining
+      # @raise [ArgumentError] If badge is nil
+      def with_trailing_badge(badge, **opts)
+        raise ArgumentError, "Badge cannot be nil" if badge.nil?
+
+        @trailing_badge = badge
+        @trailing_badge_options = opts.freeze
+        self
+      end
+
       # Determines if this menu item should be shown as active.
       # Checks in the following order:
       # 1. Custom active logic if provided in options
@@ -89,44 +126,54 @@ module Phlexi
       # @param context [Object] The context object (typically a controller) for active state checking
       # @return [Boolean] true if the item should be shown as active, false otherwise
       def active?(context)
-        # First check custom active logic if provided
-        return @options[:active].call(context) if @options[:active].respond_to?(:call)
-
-        # Then check if this item's URL matches current page
-        if context.respond_to?(:helpers) && @url
-          return true if context.helpers.current_page?(@url)
-        end
+        check_custom_active_state(context) ||
+          check_current_page_match(context) ||
+          check_nested_items_active(context)
+      end
 
-        # Finally check if any child items are active
-        @items.any? { |item| item.active?(context) }
+      # Returns a string representation of the menu item.
+      #
+      # @return [String] A human-readable representation of the menu item
+      def inspect
+        "#<#{self.class} label=#{@label.inspect} url=#{@url.inspect} items=#{@items.inspect}>"
       end
 
-      # Checks if the menu has any items.
+      private
+
+      # Sets up the badge attributes
       #
-      # @return [Boolean] true if the menu has no items, false otherwise
-      def empty?
-        @items.empty?
+      # @param leading_badge [String, Component, nil] The leading badge
+      # @param trailing_badge [String, Component, nil] The trailing badge
+      # @param options [Hash] Options containing badge configurations
+      def setup_badges(leading_badge, trailing_badge, options)
+        @leading_badge = leading_badge
+        @leading_badge_options = (options.delete(:leading_badge_options) || {}).freeze
+        @trailing_badge = trailing_badge
+        @trailing_badge_options = (options.delete(:trailing_badge_options) || {}).freeze
       end
 
-      # Returns the number of top-level items in the menu.
+      # Checks if there's custom active state logic
       #
-      # @return [Integer] The count of top-level menu items
-      def size
-        @items.size
+      # @param context [Object] The context for active state checking
+      # @return [Boolean] Result of custom active check
+      def check_custom_active_state(context)
+        @options[:active].respond_to?(:call) && @options[:active].call(context)
       end
 
-      # Checks if this menu item has any nested items.
+      # Checks if the current page matches the item's URL
       #
-      # @return [Boolean] true if the item has nested items, false otherwise
-      def nested?
-        !empty?
+      # @param context [Object] The context for URL matching
+      # @return [Boolean] Whether the current page matches
+      def check_current_page_match(context)
+        context.respond_to?(:helpers) && @url && context.helpers.current_page?(@url)
       end
 
-      # Returns a string representation of the menu item.
+      # Checks if any nested items are active
       #
-      # @return [String] A human-readable representation of the menu item
-      def inspect
-        "#<#{self.class} label=#{@label} url=#{@url} items=#{@items.map(&:inspect)}>"
+      # @param context [Object] The context for checking nested items
+      # @return [Boolean] Whether any nested items are active
+      def check_nested_items_active(context)
+        @items.any? { |item| item.active?(context) }
       end
     end
   end

data/lib/phlexi/menu/theme.rb

@@ -3,19 +3,36 @@ require "phlexi-field"
 module Phlexi
   module Menu
     class Theme < Phlexi::Field::Theme
+      # Defines the default theme structure with nil values
+      # Can be overridden in subclasses to provide custom styling
+      #
+      # @return [Hash] Default theme structure with nil values
       def self.theme
         @theme ||= {
-          nav: nil,
-          items_container: nil,
-          item_wrapper: nil,
-          item_parent: nil,
-          item_link: nil,
-          item_span: nil,
-          item_label: nil,
-          leading_badge: nil,
-          trailing_badge: nil,
-          icon: nil,
-          active: nil
+          # Container elements
+          nav: nil,                    # Navigation wrapper
+          items_container: nil,        # <ul> list container
+
+          # Item structure elements
+          item_wrapper: nil,           # <li> item wrapper
+          item_parent: nil,            # Additional class for items with visible children
+          item_link: nil,              # <a> for clickable items
+          item_span: nil,              # <span> for non-clickable items
+          item_label: nil,             # Label text wrapper
+
+          # Interactive states
+          active: nil,                 # Active/selected state
+          hover: nil,                  # Hover state
+
+          # Badge elements
+          leading_badge_wrapper: nil,  # Wrapper for leading badge
+          trailing_badge_wrapper: nil, # Wrapper for trailing badge
+          leading_badge: nil,          # Badge before label
+          trailing_badge: nil,         # Badge after label
+
+          # Icon elements
+          icon: nil,                   # Icon styling
+          icon_wrapper: nil            # Icon container
         }.freeze
       end
     end

data/lib/phlexi/menu/version.rb

@@ -2,6 +2,6 @@
 
 module Phlexi
   module Menu
-    VERSION = "0.0.3"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phlexi-menu
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-11 00:00:00.000000000 Z
+date: 2024-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex
@@ -180,6 +180,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- changes.patch
 - config.ru
 - export.json
 - export.rb
@@ -189,6 +190,7 @@ files:
 - gemfiles/rails_7.gemfile.lock
 - lib/phlexi-menu.rb
 - lib/phlexi/menu.rb
+- lib/phlexi/menu/badge.rb
 - lib/phlexi/menu/builder.rb
 - lib/phlexi/menu/component.rb
 - lib/phlexi/menu/item.rb