phlexi-menu 0.0.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cc4d5883a4c76ae7455de7f38c33639dccee507b1406549a00e1f211906020e
-  data.tar.gz: 23332831a113a1dc53515afe6449861cb8282b2f1ecd2f4dfde1eaf427cb0d52
+  metadata.gz: 77a15ed27fda6bba3dafc46555f7f796b94a18982056fb3898d73393539a02c1
+  data.tar.gz: d91ecb5053d3935209c2c68099b5615db195994da9f1ae9236bc5a9f993267e5
 SHA512:
-  metadata.gz: ab3e7aad92d888a87599f33fcffa5e52c413e8b7bffaba4852e4d07e2fdd65e1b3dbf3f031542f95995a78fbac3fd29cf4609db7c332581af23249f7b07f84c2
-  data.tar.gz: bd393a7fa7bdc00f2c20ee7227bbde090584d87f2c310cdf07d77c1cf4607871142860223f1ca267bfeedfb40bb724b3d88f04df89ef3f4eac6c80a62c59cf2a
+  metadata.gz: bc8f8b414638e5f5960f763978f3cb6e3c59ec7e745e6def67cf53a7d77c715e6b2331f3dd42aa4631279d51f06844cb2ca331557671f5fcee2128c9fc2c3f7d
+  data.tar.gz: 0d4c58a1ce2738b39ab32497a00688d0290293b844c43539418fa051339d9ba52439a87aeb59f8bcc112978e57a7f9d8cf7feb17880dcc509a0d4c455156b325

data/README.md

@@ -12,12 +12,20 @@ Phlexi::Menu is a flexible and powerful menu builder for Ruby applications. It p
 - [Usage](#usage)
   - [Basic Usage](#basic-usage)
   - [Menu Items](#menu-items)
+  - [Badge System](#badge-system)
   - [Component Options](#component-options)
+  - [Nesting and Depth Limits](#nesting-and-depth-limits)
   - [Theming](#theming)
-  - [Badge Components](#badge-components)
+    - [Static Theming](#static-theming)
+    - [Depth-Aware Theming](#depth-aware-theming)
   - [Rails Integration](#rails-integration)
 - [Advanced Usage](#advanced-usage)
+  - [Active State Detection](#active-state-detection)
   - [Component Customization](#component-customization)
+    - [Core Rendering Methods](#core-rendering-methods)
+    - [Badge Related Methods](#badge-related-methods)
+    - [Other Components](#other-components)
+    - [Helper Methods](#helper-methods)
   - [Dynamic Menus](#dynamic-menus)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -25,10 +33,11 @@ Phlexi::Menu is a flexible and powerful menu builder for Ruby applications. It p
 
 ## Features
 
-- Hierarchical menu structure with controlled nesting depth
-- Support for icons and dual-badge system (leading and trailing badges)
+- Hierarchical menu structure with intelligent depth control
+- Enhanced badge system with customizable options and wrappers
 - 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,12 +73,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)}" },
+        # Badge wrapper styles
+        leading_badge_wrapper: "flex items-center",
+        trailing_badge_wrapper: "flex items-center ml-auto",
+        # Badge styles
         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",
+        trailing_badge: "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"
       })
@@ -79,22 +91,20 @@ end
 
 # Using the menu
 menu = Phlexi::Menu::Builder.new do |m|
-  m.item "Dashboard", 
-    url: "/", 
-    icon: DashboardIcon
+  m.item "Dashboard", url: "/", icon: DashboardIcon
   
-  m.item "Users", 
-    url: "/users", 
-    leading_badge: "Beta",
-    trailing_badge: "23" do |users|
+  # Using the new fluent badge API
+  m.item "Users", url: "/users"
+    .with_leading_badge("Beta", color: "blue")
+    .with_trailing_badge("23", size: "sm") do |users|
     users.item "All Users", url: "/users"
     users.item "Add User", url: "/users/new"
   end
-  
+
   m.item "Settings", 
     url: "/settings", 
     icon: SettingsIcon,
-    leading_badge: CustomBadgeComponent.new
+    leading_badge: StatusBadge.new(type: "warning")
 end
 
 # In your view
@@ -116,6 +126,35 @@ m.item "Menu Item",
   }
 ```
 
+The new fluent badge API provides a cleaner way to add badges:
+
+```ruby
+m.item "Products"
+  .with_leading_badge("New", class: "text-blue-900")
+  .with_trailing_badge("99+", class: "text-sm")
+```
+
+### Badge System
+
+The enhanced badge system supports both simple text badges and complex component badges with customization options:
+
+```ruby
+# Simple text badges with options
+m.item "Products"
+  .with_leading_badge("New", class: "text-green-400")
+
+# Component badges
+m.item "Messages"
+  .with_leading_badge(StatusBadge.new(status: "active"))
+  .with_trailing_badge(CounterBadge.new(count: 3))
+
+# Legacy style still supported
+m.item "Legacy",
+  leading_badge: "Beta",
+  trailing_badge: "2",
+  leading_badge_options: { class: "text-green-400"},
+```
+
 ### Component Options
 
 The menu component accepts these initialization options:
@@ -128,8 +167,52 @@ 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" do |l2|   # Will be nested if max_depth > 3
+        l2.item "Level 3"
+      end
+    end
+  end
+end
+
+# Render with depth limit
+menu_component = MainMenu.new(menu, max_depth: 2)
+```
+
 ### Theming
 
+The theming system now includes dedicated wrapper elements for badges:
+
+```ruby
+def self.theme
+  super.merge({
+    # Badge containers
+    leading_badge_wrapper: "flex items-center",
+    trailing_badge_wrapper: "ml-auto",
+    
+    # Badge elements
+    leading_badge: ->(depth) {
+      ["badge", depth.zero? ? "primary" : "secondary"]
+    },
+    trailing_badge: ->(depth) {
+      ["badge", "ml-2", "level-#{depth}"]
+    }
+  })
+end
+```
+
+#### Static Theming
+
+Basic theme configuration with fixed classes:
+
 ```ruby
 class CustomMenu < Phlexi::Menu::Component
   class Theme < Theme
@@ -151,24 +234,31 @@ class CustomMenu < Phlexi::Menu::Component
 end
 ```
 
-### Badge Components
+#### Depth-Aware Theming
 
-Badges can be either strings or Phlex components:
+Advanced theme configuration with depth-sensitive classes:
 
 ```ruby
-class CustomBadgeComponent < ApplicationComponent
-  def view_template
-    div(class: "flex items-center") do
-      span(class: "h-2 w-2 rounded-full bg-blue-400")
-      span(class: "ml-2") { "New" }
+class DepthAwareMenu < Phlexi::Menu::Component
+  class Theme < Theme
+    def self.theme
+      super.merge({
+        item_wrapper: ->(depth) { "relative pl-#{depth * 4}" },
+        item_label: ->(depth) { "mx-3 text-gray-#{600 + (depth * 100)}" },
+        leading_badge: ->(depth) { 
+          ["badge", "mr-2", depth.zero? ? "primary" : "secondary"] 
+        }
+      })
     end
   end
 end
-
-# Usage
-m.item "Products", leading_badge: CustomBadgeComponent.new
 ```
 
+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
+
 ### Rails Integration
 
 In your controller:
@@ -193,8 +283,8 @@ class ApplicationController < ActionController::Base
 
       if current_user&.admin?
         m.item "Admin", 
-          url: admin_path, 
-          leading_badge: "Admin"
+          url: admin_path
+          .with_leading_badge("Admin", variant: "warning")
       end
     end
   end
@@ -202,50 +292,97 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-Note: The menu component uses Rails' `current_page?` helper for default active state detection. If you're not using Rails or want custom active state logic, provide an `active` callable to your menu items:
+## Advanced Usage
+
+### Active State Detection
+
+The menu system provides multiple ways to determine the active state of items:
 
 ```ruby
-m.item "Custom Active", url: "/path", active: ->(context) {
-  # Your custom active state logic here
-  context.request.path.start_with?("/path")
-}
+m.item "Custom Active", 
+  url: "/path", 
+  active: ->(context) {
+    # Custom active state logic
+    context.request.path.start_with?("/path")
+  }
 ```
 
-## Advanced Usage
+Default behavior checks:
+1. Custom active logic (if provided)
+2. Current page match
+3. Active state of child items
 
 ### Component Customization
 
-You can customize specific rendering steps:
+You can customize specific rendering steps by subclassing the base component and overriding specific methods.
+
+The component provides these customization points:
+
+#### Core Rendering Methods
+- `render_items(items, depth)`: Handles collection of items and nesting
+- `render_item_wrapper(item, depth)`: Wraps individual items in list elements
+- `render_item_content(item, depth)`: Chooses between link and span rendering
+- `render_item_interior(item, depth)`: Handles the item's internal layout
+
+#### Badge Related Methods
+- `render_leading_badge(item, depth)`: Renders the item's leading badge with wrapper
+- `render_trailing_badge(item, depth)`: Renders the item's trailing badge with wrapper
+- `render_badge(badge, options, type, depth)`: Core badge rendering with options support
+
+#### Other Components
+- `render_icon(icon, depth)`: Renders the icon component
+- `render_label(label, depth)`: Renders the item's label
+
+#### Helper Methods
+- `nested?(item, depth)`: Determines if an item should show nested children
+- `active?(item)`: Determines item's active state
+- `active_class(item, depth)`: Resolves active state styling
+- `themed(component, depth)`: Resolves theme values for components
+- `compute_item_wrapper_classes(item, depth)`: Computes wrapper CSS classes
+
+Each method receives the current depth as a parameter for depth-aware rendering and theming. You can override any combination of these methods to customize the rendering behavior:
 
 ```ruby
 class CustomMenu < Phlexi::Menu::Component
-  # Override just what you need
-  def render_item_interior(item)
-    div(class: "flex items-center gap-2") do
-      render_leading_badge(item.leading_badge) if item.leading_badge
-      render_icon(item.icon) if item.icon
-      span(class: themed(:item_label)) { item.label.upcase }
-      render_trailing_badge(item.trailing_badge) if item.trailing_badge
+  # Customize just the badge rendering
+  def render_badge(badge, options, type, depth)
+    if badge.is_a?(String) && type == :leading_badge
+      render_text_badge(badge, options, depth)
+    else
+      super
     end
   end
 
-  def render_leading_badge(badge)
-    div(class: tokens(themed(:leading_badge), "flex items-center")) do
-      span { "●" }
-      span(class: "ml-1") { badge }
+  private
+
+  def render_text_badge(text, options, depth)
+    span(class: themed(:leading_badge, depth)) do
+      span(class: "dot") { "•" }
+      text
     end
   end
 end
 ```
 
-The component provides these customization points:
-- `render_items`: Handles collection of items and nesting
-- `render_item_wrapper`: Wraps individual items
-- `render_item_content`: Chooses between link and span rendering
-- `render_item_interior`: Handles the item's internal layout
-- `render_leading_badge`: Renders the leading badge
-- `render_trailing_badge`: Renders the trailing badge
-- `render_icon`: Renders the icon component
+For Rails applications, you can also integrate with helpers and routes:
+
+```ruby
+class ApplicationMenu < Phlexi::Menu::Component
+  protected
+
+  def active?(item)
+    return super unless helpers&.respond_to?(:current_page?)
+    current_page?(item.url) || item.items.any? { |child| active?(child) }
+  end
+
+  def render_icon(icon, depth)
+    return super unless icon.respond_to?(:to_svg)
+    raw icon.to_svg(class: themed(:icon, depth))
+  end
+end
+```
+
+The component's modular design allows you to customize exactly what you need while maintaining the core menu functionality.
 
 ### Dynamic Menus
 
@@ -267,7 +404,10 @@ Phlexi::Menu::Builder.new do |m|
   
   # Dynamic items from database
   current_user.organizations.each do |org|
-    m.item org.name, url: organization_path(org), icon: OrgIcon
+    m.item org.name, 
+      url: organization_path(org), 
+      icon: OrgIcon,
+      trailing_badge: org.unread_notifications_count
   end
 end
 ```