easy_menu 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b1e9ced377fa41ccde18eb63585c26db224c90265189c18630cf3912bb4df9f
-  data.tar.gz: dd2dfb7d78dc212fa78c3b4f129d5ce5537fe6ef32e13677fe9506fc01b5b4e1
+  metadata.gz: b3dbed4f51e1a4df59bca564a8c684568b4b569bdbd416d83e9e572bf49a97ad
+  data.tar.gz: 5cff12c998bb96efb7c09aff77ec087a0638db79fd7721c165afa7668d85539c
 SHA512:
-  metadata.gz: f1f95ffcbff00e46f1ba6eaef34244b86da72c97d73daf97a530b712c025457d8d9f2b6ce1aef57fa5d41fcf8f329176ec5c61530244f8fde5fd25c127edbf15
-  data.tar.gz: 6a5f6e530e9c2da66101db87c0bab4002322aa75b8f3f9ea21c3eaeae42de23b4c2da3f74a2d854aeffdc5bc0f782fb87d93bff4b67dcbaf48a074ed56081718
+  metadata.gz: 7622aae3a25d009c42bc3537b63783ed0d13c094c9a671da3ebfa35229ac23e1873d093ec845baa1dd7051a824f82e8ac991eb322b8bac15265e9cc94f9d747a
+  data.tar.gz: d28ae089ae71cea05c2092be1d13705a58664ccb0d9b3df68b1ab5787f45559be28c17b9928c5d98f54a07d12b85f31bb52d9f5d7ffcd71ae74ed0f3d09e691f

data/README

@@ -1,4 +1,239 @@
 # Easy Menu
-## Make menus the easy way
 
-Supports Prototype and Jquery
+Simple menu bar and dropdown DSL for Rails views.
+
+Easy Menu provides a small Ruby DSL for building menu bars, grouped dropdowns, and menu actions in helpers or views. It ships with default styles and JavaScript behavior designed for traditional server-rendered Rails applications.
+
+Supports Prototype and jQuery integrations used by legacy projects.
+
+## Features
+
+- Ruby DSL for menu bars and dropdown menus
+- Nested menu groups and separators
+- Selection and disabled states
+- Right and left aligned menu content
+- Configurable global and per-menu behavior
+- Rails engine assets (styles and JavaScript)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'easy_menu'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+Build a menu bar in a helper:
+
+```ruby
+def users_menu
+  MenuBar.new(self) do |mb|
+    mb.menu_bar_item(link_to('All Users', users_path)).selected(params[:action] == 'index')
+    mb.menu_bar_item(link_to('Invite', new_user_invitation_path))
+
+    mb.menu('More') do |menu|
+      menu.menu_item(link_to('Roles', roles_path))
+      menu.menu_item(link_to('Permissions', permissions_path))
+    end
+  end
+end
+```
+
+Render it in a view:
+
+```erb
+<%= users_menu %>
+```
+
+## Core DSL
+
+### MenuBar
+
+Create a menu bar:
+
+```ruby
+MenuBar.new(self, theme: :default_theme) do |mb|
+  # items
+end
+```
+
+Common methods:
+
+- `menu_bar_item(content, options = {})`
+- `menu(button_text, options = {}) { |menu| ... }`
+- `group(options = {}) { |group| ... }`
+- `menu_bar_content(content = nil, options = {}, &block)`
+- `menu_bar_input(content, options = {})`
+- `separator(options = {})`
+
+### Menu
+
+Inside `menu(...)` blocks:
+
+- `menu_item(content, options = {})`
+- `group(title, options = {}) { |group| ... }`
+- `menu_content(content = nil, options = {}, &block)`
+- `separator(options = {})`
+
+### Item States
+
+Most items support:
+
+- `.selected(true_or_false)`
+- `.disabled(true_or_false = true, click_blocker_html_options = {})`
+- `.disable_when(dom_element, dom_event, js_condition, click_blocker_html_options = {})`
+
+## Alignment and Ordering
+
+Menu item alignment is set on the content wrapper:
+
+```ruby
+mb.menu_bar_item(link_to('Sign Out', destroy_user_session_path), align: :right)
+```
+
+### Right-Aligned Insert Strategy
+
+Easy Menu supports two right-aligned insertion strategies:
+
+- `:legacy_prepend` (default)
+  - Preserves historical float-right behavior.
+  - Right-aligned items are prepended internally.
+- `:preserve_definition_order`
+  - Right-aligned items keep the same order they are declared in Ruby.
+  - Useful for flexbox-based layouts.
+
+Set per menu bar:
+
+```ruby
+MenuBar.new(self, right_aligned_insert_strategy: :preserve_definition_order) do |mb|
+  mb.menu_bar_item(link_to('My Account', my_account_path), align: :right)
+  mb.menu_bar_item(link_to('Sign Out', destroy_user_session_path), align: :right)
+end
+```
+
+Set globally:
+
+```ruby
+MenuBar.config[:right_aligned_insert_strategy] = :preserve_definition_order
+```
+
+### Explicit Indexing
+
+`index` always takes precedence over insert strategy:
+
+```ruby
+mb.menu_bar_item(link_to('First', first_path), index: 0)
+```
+
+## Configuration
+
+Configuration is available through `MenuBar.config` and defaults from `EasyMenu::Configuration::Default`.
+
+Examples:
+
+- Element wrappers (`:menu_bar_element`, `:menu_item_element`, ...)
+- CSS class names (`:menu_bar_class`, `:menu_item_class`, ...)
+- State classes (`:selected_class`, `:disabled_class`)
+- Right alignment strategy (`:right_aligned_insert_strategy`)
+
+Per-menu overrides can be passed using `config:`:
+
+```ruby
+MenuBar.new(self, config: { menu_bar_element: :nav }) do |mb|
+  mb.menu_bar_item('Example')
+end
+```
+
+## HTML Options and Data Attributes
+
+Most wrapper/item calls accept standard HTML options:
+
+- `id`
+- `class`
+- `title`
+- `style`
+- `data`
+- `data-*` keys
+
+## Styling and JavaScript Notes
+
+- The gem provides default styles (`easy_menu.css.scss`) and behavior hooks.
+- `menu_bar_content_with_menu_class` defaults to `with_menu no_js`.
+- The `no_js` class is meant to be removed client-side when JavaScript is active.
+
+Projects commonly layer app-specific CSS on top of Easy Menu's baseline classes.
+
+## Common Patterns
+
+### Search Form Content in a Menu Bar
+
+```ruby
+mb.group do |group|
+  group.menu_bar_content do
+    form_tag(search_path, method: :get) { text_field_tag(:q) }
+  end
+  group.menu_bar_item(link_to('Clear', search_path)) if params[:q].present?
+end
+```
+
+### Grouped Dropdown Menu
+
+```ruby
+mb.menu('Admin') do |menu|
+  menu.group('Users') do |group|
+    group.menu_item(link_to('List', users_path))
+    group.menu_item(link_to('Invite', new_user_invitation_path))
+  end
+
+  menu.separator
+
+  menu.group('System') do |group|
+    group.menu_item(link_to('Configuration', system_configuration_path))
+  end
+end
+```
+
+## Migration Notes for Flex Layouts
+
+If your app moved menu bars from float-based CSS to flexbox:
+
+- Keep default `:legacy_prepend` unless you verify visual order is correct.
+- Prefer `:preserve_definition_order` for flex layouts where declaration order should match render order.
+- If needed, enable per-menu first, then move to global config.
+
+## Troubleshooting
+
+### Right-aligned items appear reversed
+
+Use:
+
+```ruby
+MenuBar.new(self, right_aligned_insert_strategy: :preserve_definition_order)
+```
+
+### Unexpected classes or wrappers
+
+Check `MenuBar.config` overrides and project CSS specificity.
+
+### Empty separators at the end
+
+`remove_dangling_separators` defaults to `true` and removes trailing separators.
+
+## Development
+
+- This gem is a Rails engine.
+- Main DSL entry point: `lib/menu_bar.rb`
+- Config defaults: `lib/easy_menu_configuration.rb`
+- Shared helper behavior: `lib/easy_menu_helpers.rb`
+
+## License
+
+MIT. See `MIT-LICENSE`.

data/lib/easy_menu_configuration.rb

@@ -45,7 +45,12 @@ module EasyMenu
       :menu_content_element             => :li,
       :menu_group_title_element         => :div,
       :menu_group_element               => :ul,
-      :menu_item_element                => :div
+      :menu_item_element                => :div,
+
+      # Right-aligned insertion strategy:
+      # - :legacy_prepend preserves historical float-right behavior (default)
+      # - :preserve_definition_order keeps right-aligned items in declaration order
+      :right_aligned_insert_strategy    => :legacy_prepend
     }
 
     Bootstrap =  {

data/lib/menu_bar.rb

@@ -143,14 +143,27 @@ class MenuBar
   def store_menu_bar_content(mbc, options = {})
     if options[:index]
       @content.insert(options[:index], mbc)
-    # Ensure that right aligned menu bar content appears on the page in the order it is inserted
     elsif mbc.right_aligned?
-      @content.prepend(mbc)
+      if right_aligned_insert_strategy == :preserve_definition_order
+        @content << mbc
+      else
+        # Ensure that right aligned menu bar content appears on the page in the order it is inserted
+        # when rendered with float-based right alignment (legacy behavior).
+        @content.prepend(mbc)
+      end
     else
       @content << mbc
     end
   end
 
+  def right_aligned_insert_strategy
+    strategy = @options[:right_aligned_insert_strategy] || config[:right_aligned_insert_strategy]
+    strategy = strategy.to_sym if strategy.respond_to?(:to_sym)
+    return strategy if [:legacy_prepend, :preserve_definition_order].include?(strategy)
+
+    raise ArgumentError, "Unknown right_aligned_insert_strategy: #{strategy.inspect}"
+  end
+
   # ABSTRACT CLASSES
 
   class AbstractContent

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: easy_menu
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Nicholas Jakobsen
 - Ryan Wallace
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -25,8 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.1'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -44,10 +41,8 @@ files:
 - lib/easy_menu_configuration.rb
 - lib/easy_menu_helpers.rb
 - lib/menu_bar.rb
-homepage:
 licenses: []
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -62,8 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Simple menu bar DSL for Rails views
 test_files: []