phlexi-menu 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40109076a44e4310e8cbc068e809dedfca7b9afc6227b0c7ee96acc5cf72a4c0
-  data.tar.gz: e66e40f81ee54a7f785b382679d698ef3faee3262636bed0f37912e7d9522af0
+  metadata.gz: 9bb5cb841e6404ef962a4003718f3e2f9827dd165f417dd2a1ef9f2b5d0e07b2
+  data.tar.gz: 422533e0556c9e51f5c49eb5225ecb0d0bbb4c21af00b9ac56afcf4f723b7687
 SHA512:
-  metadata.gz: 19bab094ccaac69456aa7f008bc2b17322b0ffbfc180378103373fb1f07b05d712e7992bd452618c3a283ad04dc89beddd31ed9f2b6839180315bde73c21493c
-  data.tar.gz: 0bd4f5d8d65861f622561a8d6cbe01f62a0d17b4866440e3bfda52be935c28d90a07d111e53333318ad1836e2b16f10bf73261be74015cdcfd32d5ff5b4a1c7f
+  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/export.json

@@ -9,19 +9,19 @@
   },
   {
     "path": "/Users/stefan/Documents/plutonium/phlexi-menu/export.rb",
-    "contents": "require \"json\"\nrequire \"find\"\n\ndef export_files_to_json(directory, extensions, output_file, exceptions = [])\n  # Convert extensions to lowercase for case-insensitive matching\n  extensions = extensions.map(&:downcase)\n\n  # Array to store file data\n  files_data = []\n\n  # Find all files in directory and subdirectories\n  Find.find(directory) do |path|\n    # Skip if not a file\n    next unless File.file?(path)\n    next if exceptions.any? { |exception| path.include?(exception) }\n\n    # Check if file extension matches any in our list\n    ext = File.extname(path).downcase[1..-1] # Remove the leading dot\n    next unless extensions.include?(ext)\n\n    puts path\n\n    begin\n      # Read file contents\n      contents = File.read(path)\n\n      # Add to our array\n      files_data << {\n        \"path\" => path,\n        \"contents\" => contents\n      }\n    rescue => e\n      puts \"Error reading file #{path}: #{e.message}\"\n    end\n  end\n\n  # Write to JSON file\n  File.write(output_file, JSON.pretty_generate(files_data))\n\n  puts \"Successfully exported #{files_data.length} files to #{output_file}\"\nend\n\n# Example usage (uncomment and modify as needed):\ndirectory = \"/Users/stefan/Documents/plutonium/phlexi-menu\"\nexceptions = [\"/.github/\", \"/.vscode/\", \"gemfiles\", \"pkg\", \"node_modules\"]\nextensions = [\"rb\", \"md\", \"yml\", \"yaml\", \"gemspec\"]\noutput_file = \"export.json\"\nexport_files_to_json(directory, extensions, output_file, exceptions)\n"
+    "contents": "require \"json\"\nrequire \"find\"\n\ndef export_files_to_json(directory, extensions, output_file, exceptions = [])\n  # Convert extensions to lowercase for case-insensitive matching\n  extensions = extensions.map(&:downcase)\n\n  # Array to store file data\n  files_data = []\n\n  # Find all files in directory and subdirectories\n  Find.find(directory) do |path|\n    # Skip if not a file\n    next unless File.file?(path)\n    next if exceptions.any? { |exception| path.include?(exception) }\n\n    # Check if file extension matches any in our list\n    ext = File.extname(path).downcase[1..] # Remove the leading dot\n    next unless extensions.include?(ext)\n\n    puts path\n\n    begin\n      # Read file contents\n      contents = File.read(path)\n\n      # Add to our array\n      files_data << {\n        \"path\" => path,\n        \"contents\" => contents\n      }\n    rescue => e\n      puts \"Error reading file #{path}: #{e.message}\"\n    end\n  end\n\n  # Write to JSON file\n  File.write(output_file, JSON.pretty_generate(files_data))\n\n  puts \"Successfully exported #{files_data.length} files to #{output_file}\"\nend\n\n# Example usage (uncomment and modify as needed):\ndirectory = \"/Users/stefan/Documents/plutonium/phlexi-menu\"\nexceptions = [\"/.github/\", \"/.vscode/\", \"gemfiles\", \"pkg\", \"node_modules\"]\nextensions = [\"rb\", \"md\", \"yml\", \"yaml\", \"gemspec\"]\noutput_file = \"export.json\"\nexport_files_to_json(directory, extensions, output_file, exceptions)\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/phlexi-menu/lib/phlexi/menu/builder.rb",
-    "contents": "# frozen_string_literal: true\n\nmodule Phlexi\n  module Menu\n    # Builder class for constructing hierarchical menu structures.\n    # Provides a DSL for creating nested menu items with support for labels,\n    # URLs, icons, and badges.\n    #\n    # @example Basic usage\n    #   menu = Phlexi::Menu::Builder.new do |m|\n    #     m.item \"Home\", url: \"/\"\n    #     m.item \"Products\", url: \"/products\" do |products|\n    #       products.item \"All Products\", url: \"/products\"\n    #       products.item \"Add Product\", url: \"/products/new\"\n    #     end\n    #   end\n    class Builder\n      # @return [Array<Phlexi::Menu::Item>] The collection of top-level menu items\n      attr_reader :items\n\n      # Nested Item class that inherits from Phlexi::Menu::Item\n      class Item < Phlexi::Menu::Item; end\n\n      # Initializes a new menu builder.\n      #\n      # @yield [builder] Passes the builder instance to the block for menu construction\n      # @yieldparam builder [Phlexi::Menu::Builder] The builder instance\n      def initialize(&)\n        @items = []\n\n        yield self if block_given?\n      end\n\n      # Creates and adds a new menu item to the current menu level.\n      #\n      # @param label [String] The display text for the menu item\n      # @param ** [Hash] Additional options passed to the Item constructor\n      # @yield [item] Optional block for adding nested menu items\n      # @yieldparam item [Phlexi::Menu::Item] The newly created menu item\n      # @return [Phlexi::Menu::Item] The created menu item\n      # @raise [ArgumentError] If the label is nil\n      def item(label, **, &)\n        raise ArgumentError, \"Label cannot be nil\" unless label\n\n        new_item = self.class::Item.new(label, **, &)\n        @items << new_item\n        new_item\n      end\n\n      # Checks if the menu has any items.\n      #\n      # @return [Boolean] true if the menu has no items, false otherwise\n      def empty?\n        @items.empty?\n      end\n\n      # Returns the number of top-level items in the menu.\n      #\n      # @return [Integer] The count of top-level menu items\n      def size\n        @items.size\n      end\n\n      # Returns a string representation of the menu structure.\n      #\n      # @return [String] A human-readable representation of the menu\n      def inspect\n        \"#<#{self.class} items=#{@items.map(&:label)}>\"\n      end\n    end\n  end\nend\n"
+    "contents": "# frozen_string_literal: true\n\nmodule Phlexi\n  module Menu\n    # Builder class for constructing hierarchical menu structures.\n    # Provides a DSL for creating nested menu items with support for labels,\n    # URLs, icons, and badges.\n    #\n    # @example Basic usage\n    #   menu = Phlexi::Menu::Builder.new do |m|\n    #     m.item \"Home\", url: \"/\"\n    #     m.item \"Products\", url: \"/products\" do |products|\n    #       products.item \"All Products\", url: \"/products\"\n    #       products.item \"Add Product\", url: \"/products/new\"\n    #     end\n    #   end\n    class Builder\n      # @return [Array<Phlexi::Menu::Item>] The collection of top-level menu items\n      attr_reader :items\n\n      # Nested Item class that inherits from Phlexi::Menu::Item\n      class Item < Phlexi::Menu::Item; end\n\n      # Initializes a new menu builder.\n      #\n      # @yield [builder] Passes the builder instance to the block for menu construction\n      # @yieldparam builder [Phlexi::Menu::Builder] The builder instance\n      def initialize(&)\n        @items = []\n\n        yield self if block_given?\n      end\n\n      # Creates and adds a new menu item to the current menu level.\n      #\n      # @param label [String] The display text for the menu item\n      # @param ** [Hash] Additional options passed to the Item constructor\n      # @yield [item] Optional block for adding nested menu items\n      # @yieldparam item [Phlexi::Menu::Item] The newly created menu item\n      # @return [Phlexi::Menu::Item] The created menu item\n      # @raise [ArgumentError] If the label is nil\n      def item(label, **, &)\n        raise ArgumentError, \"Label cannot be nil\" unless label\n\n        new_item = self.class::Item.new(label, **, &)\n        @items << new_item\n        new_item\n      end\n\n      # Checks if the menu has any items.\n      #\n      # @return [Boolean] true if the menu has no items, false otherwise\n      def empty?\n        @items.empty?\n      end\n\n      # Returns the number of top-level items in the menu.\n      #\n      # @return [Integer] The count of top-level menu items\n      def size\n        @items.size\n      end\n\n      # Checks if this menu item has any nested items.\n      #\n      # @return [Boolean] true if the item has nested items, false otherwise\n      def nested?\n        !empty?\n      end\n\n      # Returns a string representation of the menu structure.\n      #\n      # @return [String] A human-readable representation of the menu\n      def inspect\n        \"#<#{self.class} items=#{@items.map(&:inspect)}>\"\n      end\n    end\n  end\nend\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/phlexi-menu/lib/phlexi/menu/component.rb",
-    "contents": "# frozen_string_literal: true\n\nrequire \"phlex\"\n\nmodule Phlexi\n  module Menu\n    # Base menu component that other menu renderers can inherit from.\n    # Provides the core rendering logic for hierarchical menus with support\n    # for theming, icons, badges, and active state detection.\n    #\n    # @example Basic usage\n    #   class MyMenu < Phlexi::Menu::Component\n    #     class Theme < Theme\n    #       def self.theme\n    #         super.merge({\n    #           nav: \"bg-white shadow\",\n    #           item_label: \"text-gray-600\"\n    #         })\n    #       end\n    #     end\n    #   end\n    class Component < COMPONENT_BASE\n      # Theme class for customizing menu appearance\n      class Theme < Phlexi::Menu::Theme; end\n\n      # @return [Integer] The default maximum nesting depth for menu items\n      DEFAULT_MAX_DEPTH = 3\n\n      # Initializes a new menu component.\n      #\n      # @param menu [Phlexi::Menu::Builder] The menu structure to render\n      # @param max_depth [Integer] Maximum nesting depth for menu items\n      # @param options [Hash] Additional options passed to rendering methods\n      def initialize(menu, max_depth: DEFAULT_MAX_DEPTH, **options)\n        @menu = menu\n        @max_depth = max_depth\n        @options = options\n        super()\n      end\n\n      # Renders the menu structure as HTML.\n      #\n      # @return [String] The rendered HTML\n      def view_template\n        nav(class: themed(:nav)) do\n          render_items(@menu.items)\n        end\n      end\n\n      protected\n\n      # Renders a collection of menu items with nesting support.\n      #\n      # @param items [Array<Phlexi::Menu::Item>] The items to render\n      # @param depth [Integer] Current nesting depth\n      def render_items(items, depth = 0)\n        return if depth >= @max_depth\n        return if items.empty?\n\n        ul(class: themed(:items_container)) do\n          items.each do |item|\n            render_item_wrapper(item, depth)\n          end\n        end\n      end\n\n      # Renders the wrapper element for a menu item.\n      #\n      # @param item [Phlexi::Menu::Item] The item to wrap\n      # @param depth [Integer] Current nesting depth\n      def render_item_wrapper(item, depth)\n        li(class: tokens(\n          themed(:item_wrapper),\n          active_class(item),\n          item_parent_class(item)\n        )) do\n          render_item_content(item)\n          render_items(item.items, depth + 1) if item.items.any?\n        end\n      end\n\n      # Renders the content of a menu item, choosing between link and span.\n      #\n      # @param item [Phlexi::Menu::Item] The item to render content for\n      def render_item_content(item)\n        if item.url\n          render_item_link(item)\n        else\n          render_item_span(item)\n        end\n      end\n\n      # Renders a menu item as a link.\n      #\n      # @param item [Phlexi::Menu::Item] The item to render as a link\n      def render_item_link(item)\n        a(href: item.url, class: themed(:item_link)) do\n          render_item_interior(item)\n        end\n      end\n\n      # Renders a menu item as a span (for non-linking items).\n      #\n      # @param item [Phlexi::Menu::Item] The item to render as a span\n      def render_item_span(item)\n        span(class: themed(:item_span)) do\n          render_item_interior(item)\n        end\n      end\n\n      # Renders the interior content of a menu item (badges, icon, label).\n      #\n      # @param item [Phlexi::Menu::Item] The item to render interior content for\n      def render_item_interior(item)\n        render_leading_badge(item.leading_badge) if item.leading_badge\n        render_icon(item.icon) if item.icon\n        render_label(item.label)\n        render_trailing_badge(item.trailing_badge) if item.trailing_badge\n      end\n\n      # Renders the item's label.\n      #\n      # @param label [String, Component] The label to render\n      def render_label(label)\n        phlexi_render(label) {\n          span(class: themed(:item_label)) { label }\n        }\n      end\n\n      # Renders the item's leading badge.\n      #\n      # @param badge [String, Component] The leading badge to render\n      def render_leading_badge(badge)\n        phlexi_render(badge) {\n          span(class: themed(:leading_badge)) { badge }\n        }\n      end\n\n      # Renders the item's trailing badge.\n      #\n      # @param badge [String, Component] The trailing badge to render\n      def render_trailing_badge(badge)\n        phlexi_render(badge) {\n          span(class: themed(:trailing_badge)) { badge }\n        }\n      end\n\n      # Renders the item's icon.\n      #\n      # @param icon [Class] The icon component class to render\n      def render_icon(icon)\n        return unless icon\n\n        div(class: themed(:icon_wrapper)) do\n          render icon.new(class: themed(:icon))\n        end\n      end\n\n      # Determines the active state class for an item.\n      #\n      # @param item [Phlexi::Menu::Item] The item to check active state for\n      # @return [String, nil] The active class name or nil\n      def active_class(item)\n        item.active?(context) ? themed(:active) : nil\n      end\n\n      # Determines the parent state class for an item.\n      #\n      # @param item [Phlexi::Menu::Item] The item to check parent state for\n      # @return [String, nil] The parent class name or nil\n      def item_parent_class(item)\n        item.items.any? ? themed(:item_parent) : nil\n      end\n\n      # Resolves a theme component to its CSS classes.\n      #\n      # @param component [Symbol] The theme component to resolve\n      # @return [String, nil] The resolved CSS classes or nil\n      def themed(component)\n        self.class::Theme.instance.resolve_theme(component)\n      end\n\n      # Renders either a component or simple value with fallback.\n      #\n      # @param arg [Object] The value to render\n      # @yield The default rendering block\n      # @raise [ArgumentError] If no block is provided\n      def phlexi_render(arg, &)\n        return unless arg\n        raise ArgumentError, \"phlexi_render requires a default render block\" unless block_given?\n\n        if arg.class < Phlex::SGML || arg.respond_to?(:render_in)\n          render arg\n        elsif arg.respond_to?(:to_proc)\n          instance_exec(&arg)\n        else\n          yield\n        end\n      end\n    end\n  end\nend\n"
+    "contents": "# frozen_string_literal: true\n\nrequire \"phlex\"\n\nmodule Phlexi\n  module Menu\n    # Base menu component that other menu renderers can inherit from.\n    # Provides the core rendering logic for hierarchical menus with support\n    # for theming, icons, badges, and active state detection.\n    #\n    # @example Basic usage\n    #   class MyMenu < Phlexi::Menu::Component\n    #     class Theme < Theme\n    #       def self.theme\n    #         super.merge({\n    #           nav: \"bg-white shadow\",\n    #           item_label: \"text-gray-600\"\n    #         })\n    #       end\n    #     end\n    #   end\n    class Component < COMPONENT_BASE\n      # Theme class for customizing menu appearance\n      class Theme < Phlexi::Menu::Theme; end\n\n      # @return [Integer] The default maximum nesting depth for menu items\n      DEFAULT_MAX_DEPTH = 3\n\n      # Initializes a new menu component.\n      #\n      # @param menu [Phlexi::Menu::Builder] The menu structure to render\n      # @param max_depth [Integer] Maximum nesting depth for menu items\n      # @param options [Hash] Additional options passed to rendering methods\n      def initialize(menu, max_depth: default_max_depth, **options)\n        @menu = menu\n        @max_depth = max_depth\n        @options = options\n        super()\n      end\n\n      # Renders the menu structure as HTML.\n      #\n      # @return [String] The rendered HTML\n      def view_template\n        nav(class: themed(:nav)) do\n          render_items(@menu.items)\n        end\n      end\n\n      protected\n\n      # Renders a collection of menu items with nesting support.\n      #\n      # @param items [Array<Phlexi::Menu::Item>] The items to render\n      # @param depth [Integer] Current nesting depth\n      def render_items(items, depth = 0)\n        return if depth >= @max_depth\n        return if items.empty?\n\n        ul(class: themed(:items_container)) do\n          items.each do |item|\n            render_item_wrapper(item, depth)\n          end\n        end\n      end\n\n      # Renders the wrapper element for a menu item.\n      #\n      # @param item [Phlexi::Menu::Item] The item to wrap\n      # @param depth [Integer] Current nesting depth\n      def render_item_wrapper(item, depth)\n        li(class: tokens(\n          themed(:item_wrapper),\n          active_class(item),\n          item_parent_class(item)\n        )) do\n          render_item_content(item)\n          render_items(item.items, depth + 1) if item.items.any?\n        end\n      end\n\n      # Renders the content of a menu item, choosing between link and span.\n      #\n      # @param item [Phlexi::Menu::Item] The item to render content for\n      def render_item_content(item)\n        if item.url\n          render_item_link(item)\n        else\n          render_item_span(item)\n        end\n      end\n\n      # Renders a menu item as a link.\n      #\n      # @param item [Phlexi::Menu::Item] The item to render as a link\n      def render_item_link(item)\n        a(href: item.url, class: themed(:item_link)) do\n          render_item_interior(item)\n        end\n      end\n\n      # Renders a menu item as a span (for non-linking items).\n      #\n      # @param item [Phlexi::Menu::Item] The item to render as a span\n      def render_item_span(item)\n        span(class: themed(:item_span)) do\n          render_item_interior(item)\n        end\n      end\n\n      # Renders the interior content of a menu item (badges, icon, label).\n      #\n      # @param item [Phlexi::Menu::Item] The item to render interior content for\n      def render_item_interior(item)\n        render_leading_badge(item.leading_badge) if item.leading_badge\n        render_icon(item.icon) if item.icon\n        render_label(item.label)\n        render_trailing_badge(item.trailing_badge) if item.trailing_badge\n      end\n\n      # Renders the item's label.\n      #\n      # @param label [String, Component] The label to render\n      def render_label(label)\n        phlexi_render(label) {\n          span(class: themed(:item_label)) { label }\n        }\n      end\n\n      # Renders the item's leading badge.\n      #\n      # @param badge [String, Component] The leading badge to render\n      def render_leading_badge(badge)\n        phlexi_render(badge) {\n          span(class: themed(:leading_badge)) { badge }\n        }\n      end\n\n      # Renders the item's trailing badge.\n      #\n      # @param badge [String, Component] The trailing badge to render\n      def render_trailing_badge(badge)\n        phlexi_render(badge) {\n          span(class: themed(:trailing_badge)) { badge }\n        }\n      end\n\n      # Renders the item's icon.\n      #\n      # @param icon [Class] The icon component class to render\n      def render_icon(icon)\n        return unless icon\n\n        div(class: themed(:icon_wrapper)) do\n          render icon.new(class: themed(:icon))\n        end\n      end\n\n      # Determines the active state class for an item.\n      #\n      # @param item [Phlexi::Menu::Item] The item to check active state for\n      # @return [String, nil] The active class name or nil\n      def active_class(item)\n        item.active?(self) ? themed(:active) : nil\n      end\n\n      # Determines the parent state class for an item.\n      #\n      # @param item [Phlexi::Menu::Item] The item to check parent state for\n      # @return [String, nil] The parent class name or nil\n      def item_parent_class(item)\n        item.items.any? ? themed(:item_parent) : nil\n      end\n\n      # Resolves a theme component to its CSS classes.\n      #\n      # @param component [Symbol] The theme component to resolve\n      # @return [String, nil] The resolved CSS classes or nil\n      def themed(component)\n        self.class::Theme.instance.resolve_theme(component)\n      end\n\n      # Renders either a component or simple value with fallback.\n      #\n      # @param arg [Object] The value to render\n      # @yield The default rendering block\n      # @raise [ArgumentError] If no block is provided\n      def phlexi_render(arg, &)\n        return unless arg\n        raise ArgumentError, \"phlexi_render requires a default render block\" unless block_given?\n\n        if arg.class < Phlex::SGML || arg.respond_to?(:render_in)\n          render arg\n        elsif arg.respond_to?(:to_proc)\n          instance_exec(&arg)\n        else\n          yield\n        end\n      end\n\n      def default_max_depth = self.class::DEFAULT_MAX_DEPTH\n    end\n  end\nend\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/phlexi-menu/lib/phlexi/menu/item.rb",
-    "contents": "# frozen_string_literal: true\n\nmodule Phlexi\n  module Menu\n    # Represents a single menu item in the navigation hierarchy.\n    # Each item can have a label, URL, icon, badges, and nested child items.\n    #\n    # @example Basic menu item\n    #   item = Item.new(\"Home\", url: \"/\")\n    #\n    # @example Menu item with badges and icon\n    #   item = Item.new(\"Products\",\n    #     url: \"/products\",\n    #     icon: ProductIcon,\n    #     leading_badge: \"New\",\n    #     trailing_badge: \"5\")\n    #\n    # @example Nested menu items\n    #   item = Item.new(\"Admin\") do |admin|\n    #     admin.item \"Users\", url: \"/admin/users\"\n    #     admin.item \"Settings\", url: \"/admin/settings\"\n    #   end\n    class Item\n      # @return [String] The display text for the menu item\n      attr_reader :label\n\n      # @return [String, nil] The URL the menu item links to\n      attr_reader :url\n\n      # @return [Class, nil] The icon component class to be rendered\n      attr_reader :icon\n\n      # @return [String, Component, nil] The badge displayed before the label\n      attr_reader :leading_badge\n\n      # @return [String, Component, nil] The badge displayed after the label\n      attr_reader :trailing_badge\n\n      # @return [Array<Item>] Collection of nested menu items\n      attr_reader :items\n\n      # @return [Hash] Additional options for customizing the menu item\n      attr_reader :options\n\n      # Initializes a new menu item.\n      #\n      # @param label [String] The display text for the menu item\n      # @param url [String, nil] The URL the menu item links to\n      # @param icon [Class, nil] The icon component class\n      # @param leading_badge [String, Component, nil] Badge displayed before the label\n      # @param trailing_badge [String, Component, nil] Badge displayed after the label\n      # @param options [Hash] Additional options (e.g., :active for custom active state logic)\n      # @yield [item] Optional block for adding nested items\n      # @yieldparam item [Item] The newly created menu item\n      # @raise [ArgumentError] If the label is nil or empty\n      def initialize(label, url: nil, icon: nil, leading_badge: nil, trailing_badge: nil, **options, &)\n        raise ArgumentError, \"Label cannot be nil\" unless label\n\n        @label = label\n        @url = url\n        @icon = icon\n        @leading_badge = leading_badge\n        @trailing_badge = trailing_badge\n        @options = options\n        @items = []\n\n        yield self if block_given?\n      end\n\n      # Creates and adds a nested menu item.\n      #\n      # @param label [String] The display text for the nested item\n      # @param ** [Hash] Additional options passed to the Item constructor\n      # @yield [item] Optional block for adding further nested items\n      # @yieldparam item [Item] The newly created nested item\n      # @return [Item] The created nested item\n      def item(label, **, &)\n        new_item = self.class.new(label, **, &)\n        @items << new_item\n        new_item\n      end\n\n      # Determines if this menu item should be shown as active.\n      # Checks in the following order:\n      # 1. Custom active logic if provided in options\n      # 2. URL match with current page\n      # 3. Active state of any child items\n      #\n      # @param context [Object] The context object (typically a controller) for active state checking\n      # @return [Boolean] true if the item should be shown as active, false otherwise\n      def active?(context)\n        # First check custom active logic if provided\n        return @options[:active].call(context) if @options[:active].respond_to?(:call)\n\n        # Then check if this item's URL matches current page\n        if context.respond_to?(:helpers) && @url\n          return true if context.helpers.current_page?(@url)\n        end\n\n        # Finally check if any child items are active\n        @items.any? { |item| item.active?(context) }\n      end\n\n      # Checks if this menu item has any nested items.\n      #\n      # @return [Boolean] true if the item has nested items, false otherwise\n      def nested?\n        !@items.empty?\n      end\n\n      # Returns a string representation of the menu item.\n      #\n      # @return [String] A human-readable representation of the menu item\n      def inspect\n        \"#<#{self.class} label=#{@label} url=#{@url} items=#{@items.map(&:label)}>\"\n      end\n    end\n  end\nend\n"
+    "contents": "# frozen_string_literal: true\n\nmodule Phlexi\n  module Menu\n    # Represents a single menu item in the navigation hierarchy.\n    # Each item can have a label, URL, icon, badges, and nested child items.\n    #\n    # @example Basic menu item\n    #   item = Item.new(\"Home\", url: \"/\")\n    #\n    # @example Menu item with badges and icon\n    #   item = Item.new(\"Products\",\n    #     url: \"/products\",\n    #     icon: ProductIcon,\n    #     leading_badge: \"New\",\n    #     trailing_badge: \"5\")\n    #\n    # @example Nested menu items\n    #   item = Item.new(\"Admin\") do |admin|\n    #     admin.item \"Users\", url: \"/admin/users\"\n    #     admin.item \"Settings\", url: \"/admin/settings\"\n    #   end\n    class Item\n      # @return [String] The display text for the menu item\n      attr_reader :label\n\n      # @return [String, nil] The URL the menu item links to\n      attr_reader :url\n\n      # @return [Class, nil] The icon component class to be rendered\n      attr_reader :icon\n\n      # @return [String, Component, nil] The badge displayed before the label\n      attr_reader :leading_badge\n\n      # @return [String, Component, nil] The badge displayed after the label\n      attr_reader :trailing_badge\n\n      # @return [Array<Item>] Collection of nested menu items\n      attr_reader :items\n\n      # @return [Hash] Additional options for customizing the menu item\n      attr_reader :options\n\n      # Initializes a new menu item.\n      #\n      # @param label [String] The display text for the menu item\n      # @param url [String, nil] The URL the menu item links to\n      # @param icon [Class, nil] The icon component class\n      # @param leading_badge [String, Component, nil] Badge displayed before the label\n      # @param trailing_badge [String, Component, nil] Badge displayed after the label\n      # @param options [Hash] Additional options (e.g., :active for custom active state logic)\n      # @yield [item] Optional block for adding nested items\n      # @yieldparam item [Item] The newly created menu item\n      # @raise [ArgumentError] If the label is nil or empty\n      def initialize(label, url: nil, icon: nil, leading_badge: nil, trailing_badge: nil, **options, &)\n        raise ArgumentError, \"Label cannot be nil\" unless label\n\n        @label = label\n        @url = url\n        @icon = icon\n        @leading_badge = leading_badge\n        @trailing_badge = trailing_badge\n        @options = options\n        @items = []\n\n        yield self if block_given?\n      end\n\n      # Creates and adds a nested menu item.\n      #\n      # @param label [String] The display text for the nested item\n      # @param ** [Hash] Additional options passed to the Item constructor\n      # @yield [item] Optional block for adding further nested items\n      # @yieldparam item [Item] The newly created nested item\n      # @return [Item] The created nested item\n      def item(label, **, &)\n        new_item = self.class.new(label, **, &)\n        @items << new_item\n        new_item\n      end\n\n      # Determines if this menu item should be shown as active.\n      # Checks in the following order:\n      # 1. Custom active logic if provided in options\n      # 2. URL match with current page\n      # 3. Active state of any child items\n      #\n      # @param context [Object] The context object (typically a controller) for active state checking\n      # @return [Boolean] true if the item should be shown as active, false otherwise\n      def active?(context)\n        # First check custom active logic if provided\n        return @options[:active].call(context) if @options[:active].respond_to?(:call)\n\n        # Then check if this item's URL matches current page\n        if context.respond_to?(:helpers) && @url\n          return true if context.helpers.current_page?(@url)\n        end\n\n        # Finally check if any child items are active\n        @items.any? { |item| item.active?(context) }\n      end\n\n      # Checks if the menu has any items.\n      #\n      # @return [Boolean] true if the menu has no items, false otherwise\n      def empty?\n        @items.empty?\n      end\n\n      # Returns the number of top-level items in the menu.\n      #\n      # @return [Integer] The count of top-level menu items\n      def size\n        @items.size\n      end\n\n      # Checks if this menu item has any nested items.\n      #\n      # @return [Boolean] true if the item has nested items, false otherwise\n      def nested?\n        !empty?\n      end\n\n      # Returns a string representation of the menu item.\n      #\n      # @return [String] A human-readable representation of the menu item\n      def inspect\n        \"#<#{self.class} label=#{@label} url=#{@url} items=#{@items.map(&:inspect)}>\"\n      end\n    end\n  end\nend\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/phlexi-menu/lib/phlexi/menu/theme.rb",

data/export.rb

@@ -15,7 +15,7 @@ def export_files_to_json(directory, extensions, output_file, exceptions = [])
     next if exceptions.any? { |exception| path.include?(exception) }
 
     # Check if file extension matches any in our list
-    ext = File.extname(path).downcase[1..-1] # Remove the leading dot
+    ext = File.extname(path).downcase[1..] # Remove the leading dot
     next unless extensions.include?(ext)
 
     puts path

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/builder.rb

@@ -61,11 +61,18 @@ module Phlexi
         @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
       def inspect
-        "#<#{self.class} items=#{@items.map(&:label)}>"
+        "#<#{self.class} items=#{@items.map(&:inspect)}>"
       end
     end
   end

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
@@ -31,16 +31,13 @@ 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
-      def initialize(menu, max_depth: DEFAULT_MAX_DEPTH, **options)
+      def initialize(menu, max_depth: default_max_depth, **options)
         @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)
@@ -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?(context) ? 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.
@@ -197,6 +246,8 @@ module Phlexi
           yield
         end
       end
+
+      def default_max_depth = self.class::DEFAULT_MAX_DEPTH
     end
   end
 end

data/lib/phlexi/menu/item.rb

@@ -101,18 +101,32 @@ module Phlexi
         @items.any? { |item| item.active?(context) }
       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?
-        !@items.empty?
+        !empty?
       end
 
       # Returns a string representation of the menu item.
       #
       # @return [String] A human-readable representation of the menu item
       def inspect
-        "#<#{self.class} label=#{@label} url=#{@url} items=#{@items.map(&:label)}>"
+        "#<#{self.class} label=#{@label} url=#{@url} items=#{@items.map(&:inspect)}>"
       end
     end
   end

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.2"
+    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.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Stefan Froelich