phlexi-menu 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cc4d5883a4c76ae7455de7f38c33639dccee507b1406549a00e1f211906020e
-  data.tar.gz: 23332831a113a1dc53515afe6449861cb8282b2f1ecd2f4dfde1eaf427cb0d52
+  metadata.gz: 9bb5cb841e6404ef962a4003718f3e2f9827dd165f417dd2a1ef9f2b5d0e07b2
+  data.tar.gz: 422533e0556c9e51f5c49eb5225ecb0d0bbb4c21af00b9ac56afcf4f723b7687
 SHA512:
-  metadata.gz: ab3e7aad92d888a87599f33fcffa5e52c413e8b7bffaba4852e4d07e2fdd65e1b3dbf3f031542f95995a78fbac3fd29cf4609db7c332581af23249f7b07f84c2
-  data.tar.gz: bd393a7fa7bdc00f2c20ee7227bbde090584d87f2c310cdf07d77c1cf4607871142860223f1ca267bfeedfb40bb724b3d88f04df89ef3f4eac6c80a62c59cf2a
+  metadata.gz: 2acde964c44d59ba554b024e83143d784214faf41d74cb823152a86c98dd88863d659910e3bb21f5cd2f9e2c4c7445dc2344c8260c9977d1af9cc50f4929246f
+  data.tar.gz: 9e651553370ad7a00ff40c0243b36729054208531eae757b945220423bc27075df0304e47f591f1c66b68a91265ed8567aa70b83653b3d69a48033fbe99392a3

data/README.md

@@ -13,7 +13,10 @@ Phlexi::Menu is a flexible and powerful menu builder for Ruby applications. It p
   - [Basic Usage](#basic-usage)
   - [Menu Items](#menu-items)
   - [Component Options](#component-options)
+  - [Nesting and Depth Limits](#nesting-and-depth-limits)
   - [Theming](#theming)
+    - [Static Theming](#static-theming)
+    - [Depth-Aware Theming](#depth-aware-theming)
   - [Badge Components](#badge-components)
   - [Rails Integration](#rails-integration)
 - [Advanced Usage](#advanced-usage)
@@ -25,10 +28,11 @@ Phlexi::Menu is a flexible and powerful menu builder for Ruby applications. It p
 
 ## Features
 
-- Hierarchical menu structure with controlled nesting depth
+- Hierarchical menu structure with intelligent depth control
 - Support for icons and dual-badge system (leading and trailing badges)
 - Intelligent active state detection
-- Flexible theming system
+- Flexible theming system with depth awareness
+- Smart nesting behavior based on depth limits
 - Works seamlessly with Phlex components
 - Rails-compatible URL handling
 - Customizable rendering components
@@ -64,14 +68,15 @@ class MainMenu < Phlexi::Menu::Component
       super.merge({
         nav: "bg-white shadow",
         items_container: "space-y-1",
-        item_wrapper: "relative",
+        item_wrapper: ->(depth) { "relative pl-#{depth * 4}" },
         item_link: "flex items-center px-4 py-2 hover:bg-gray-50",
         item_span: "flex items-center px-4 py-2",
-        item_label: "mx-3",
+        item_label: ->(depth) { "mx-3 text-gray-#{600 + (depth * 100)}" },
         leading_badge: "mr-2 px-2 py-0.5 text-xs rounded-full bg-blue-100 text-blue-600",
         trailing_badge: "ml-auto px-2 py-0.5 text-xs rounded-full bg-red-100 text-red-600",
         icon: "h-5 w-5",
-        active: "bg-blue-50 text-blue-600"
+        active: "bg-blue-50 text-blue-600",
+        item_parent: "has-children"
       })
     end
   end
@@ -90,7 +95,7 @@ menu = Phlexi::Menu::Builder.new do |m|
     users.item "All Users", url: "/users"
     users.item "Add User", url: "/users/new"
   end
-  
+
   m.item "Settings", 
     url: "/settings", 
     icon: SettingsIcon,
@@ -128,8 +133,54 @@ MainMenu.new(
 )
 ```
 
+### Nesting and Depth Limits
+
+Phlexi::Menu intelligently handles menu nesting based on the specified maximum depth:
+
+```ruby
+# Create a deeply nested menu structure
+menu = Phlexi::Menu::Builder.new do |m|
+  m.item "Level 0" do |l0|     # Will be nested (depth 0)
+    l0.item "Level 1" do |l1|  # Will be nested if max_depth > 2
+      l1.item "Level 2"        # Will be nested if max_depth > 3
+        l1.item "Level 3"      # Won't be nested if max_depth <= 3
+      end
+    end
+  end
+end
+
+# Render with depth limit
+menu_component = MainMenu.new(menu, max_depth: 2)
+```
+
+Key behaviors:
+- Items are only treated as nested if their children can be rendered within the depth limit
+- Parent styling classes (item_parent theme) are only applied to items whose children will be shown
+- Nesting structure automatically adjusts based on the max_depth setting
+- Depth-aware theme values receive the actual rendered depth of each item
+
+Example with max_depth of 2:
+```ruby
+menu = Phlexi::Menu::Builder.new do |m|
+  m.item "Products" do |products|          # depth 0, gets parent styling
+    products.item "Categories" do |cats|   # depth 1, gets parent styling
+      cats.item "Electronics"              # depth 2, no parent styling
+      cats.item "Books" do |books|         # depth 2, no parent styling
+        books.item "Fiction"               # not rendered (depth 3)
+      end
+    end
+  end
+end
+```
+
 ### Theming
 
+Phlexi::Menu provides two approaches to theming: static and depth-aware.
+
+#### Static Theming
+
+Basic theme configuration with fixed classes:
+
 ```ruby
 class CustomMenu < Phlexi::Menu::Component
   class Theme < Theme
@@ -151,6 +202,70 @@ class CustomMenu < Phlexi::Menu::Component
 end
 ```
 
+#### Depth-Aware Theming
+
+Advanced theme configuration with depth-sensitive classes:
+
+```ruby
+class DepthAwareMenu < Phlexi::Menu::Component
+  class Theme < Theme
+    def self.theme
+      super.merge({
+        # Static classes
+        nav: "bg-white shadow",
+        
+        # Progressive indentation
+        item_wrapper: ->(depth) { "relative pl-#{depth * 4}" },
+        
+        # Gradually fading text
+        item_label: ->(depth) { "mx-3 text-gray-#{600 + (depth * 100)}" },
+        
+        # Different icon styles per level
+        icon: ->(depth) {
+          base = "h-5 w-5"
+          color = depth.zero? ? "text-primary" : "text-gray-400"
+          [base, color]
+        },
+        
+        # Smaller text at deeper levels
+        item_link: ->(depth) {
+          size = depth.zero? ? "text-base" : "text-sm"
+          ["flex items-center px-4 py-2 hover:bg-gray-50", size]
+        }
+      })
+    end
+  end
+end
+```
+
+Theme values can be either:
+- Static strings for consistent styling
+- Arrays of classes that will be joined
+- Callables (procs/lambdas) that receive the current depth and return strings or arrays
+
+### Advanced Usage
+
+#### Component Customization
+
+You can customize the nesting behavior by overriding the nested? method:
+
+```ruby
+class CustomMenu < Phlexi::Menu::Component
+  protected
+
+  def nested?(item, depth)
+    # Custom logic for when to treat items as nested
+    return false if depth >= @max_depth - 1  # Reserve last level
+    return false if item.items.empty?        # No empty parents
+    
+    # Allow nesting only for items with certain attributes
+    item.options[:allow_nesting]
+  end
+end
+```
+
+
+
 ### Badge Components
 
 Badges can be either strings or Phlex components:
@@ -295,4 +410,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/radioa
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/gemfiles/default.gemfile.lock

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

data/gemfiles/rails_7.gemfile.lock

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

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
@@ -38,9 +38,6 @@ module Phlexi
         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)
@@ -57,7 +54,7 @@ module Phlexi
         return if depth >= @max_depth
         return if items.empty?
 
-        ul(class: themed(:items_container)) do
+        ul(class: themed(:items_container, depth)) do
           items.each do |item|
             render_item_wrapper(item, depth)
           end
@@ -70,114 +67,166 @@ module Phlexi
       # @param depth [Integer] Current nesting depth
       def render_item_wrapper(item, depth)
         li(class: tokens(
-          themed(:item_wrapper),
-          active_class(item),
-          item_parent_class(item)
+          themed(:item_wrapper, depth),
+          item_parent_class(item, depth),
+          active?(item) ? themed(:active, depth) : nil
         )) do
-          render_item_content(item)
-          render_items(item.items, depth + 1) if item.items.any?
+          render_item_content(item, depth)
+          render_items(item.items, depth + 1) if nested?(item, depth)
         end
       end
 
+      def nested?(item, depth)
+        has_children = item.items.any?
+        within_depth = (depth + 1) < @max_depth
+        has_children && within_depth
+      end
+
+      def item_parent_class(item, depth)
+        nested?(item, depth) ? themed(:item_parent, depth) : nil
+      end
+
+      def active?(item)
+        item.active?(self)
+      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
+      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
+      def render_item_link(item, depth)
+        a(
+          href: item.url,
+          class: tokens(
+            themed(:item_link, depth),
+            active?(item) ? themed(:active, depth) : nil
+          )
+        ) 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
+      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
+      def render_item_interior(item, depth)
+        render_leading_badge(item.leading_badge, depth) if item.leading_badge
+        render_icon(item.icon, depth) if item.icon
+        render_label(item.label, depth)
+        render_trailing_badge(item.trailing_badge, depth) if item.trailing_badge
       end
 
       # Renders the item's label.
       #
       # @param label [String, Component] The label to render
-      def render_label(label)
+      # @param depth [Integer] Current nesting depth
+      def render_label(label, depth)
         phlexi_render(label) {
-          span(class: themed(:item_label)) { label }
+          span(class: themed(:item_label, depth)) { label }
         }
       end
 
       # Renders the item's leading badge.
       #
       # @param badge [String, Component] The leading badge to render
-      def render_leading_badge(badge)
+      # @param depth [Integer] Current nesting depth
+      def render_leading_badge(badge, depth)
         phlexi_render(badge) {
-          span(class: themed(:leading_badge)) { badge }
+          span(class: themed(:leading_badge, depth)) { badge }
         }
       end
 
       # Renders the item's trailing badge.
       #
       # @param badge [String, Component] The trailing badge to render
-      def render_trailing_badge(badge)
+      # @param depth [Integer] Current nesting depth
+      def render_trailing_badge(badge, depth)
         phlexi_render(badge) {
-          span(class: themed(:trailing_badge)) { badge }
+          span(class: themed(:trailing_badge, depth)) { badge }
         }
       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
+      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)
+        item.nested? && (depth + 1) < @max_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.

data/lib/phlexi/menu/theme.rb

@@ -3,19 +3,34 @@ 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: 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.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlexi-menu
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Stefan Froelich