petit_poucet 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fea8dd68f86a327004fdfa49d7e456e555988945d1f19d63dbec6ac5fca67fb
-  data.tar.gz: 30cddd336cebff65300d98d76e7f98051d6d3763c5926084ef8892cc4c4b543d
+  metadata.gz: 9af4ab73179b6f7ec11b872254231821a51f3f58ca6af6900dc3ecbddb128994
+  data.tar.gz: 7840558d52da64060b0a39d45f6288647726f845fc071f9269d53eabe8cae890
 SHA512:
-  metadata.gz: d3617a2a030e6de249b7049481e5dfca9836c29219d6457486cfc23f1bb5035f8a1b4fc19b7dfee70b5ed73d5427bc97d5ea3e07bdeb1ea17d97ea2b77d51f4e
-  data.tar.gz: 0c9fafd8c07145129bd13b74fef5908dc62eb25548cb3cf1bf71a6afc834889442528f77cb24f7707784987a084d17cebf5416d8a9655bc50ebc6226ddce1b28
+  metadata.gz: 62469923081b601fe3f218312507ab549f841827c1349a4ba960ad4af63a9811c2857a4eaecd6d21b2cd92afddbcdbb1394c6b1ab0c181e2ce977633d2ba6f41
+  data.tar.gz: b1e22b547b0a80cdc6a44150f18a134cc915f0b4b98d94284487fef1923b40e1684e989d80cddc5a079587944134698c10eb533c014cb30682bc92627647584d

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2025-12-10
+
+### Added
+
+- `breadcrumb_group` to apply shared `only:`/`except:` filters to multiple breadcrumbs
+- Conditional `clear_breadcrumbs` with `only:` and `except:` options
+- Nested groups with intelligent option merging (intersection for `:only`, union for `:except`)
+
 ## [1.0.0] - 2025-12-03
 
 ### Added

data/README.md

@@ -1,14 +1,25 @@
-# Petit Poucet
+# Petit Poucet 🥖
 
-[![CI](https://github.com/Sbastien/petit_poucet/actions/workflows/ci.yml/badge.svg)](https://github.com/Sbastien/petit_poucet/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/petit_poucet.svg)](https://rubygems.org/gems/petit_poucet)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![gem version](https://img.shields.io/gem/v/petit_poucet.svg)](https://rubygems.org/gems/petit_poucet)
+[![gem downloads](https://img.shields.io/gem/dt/petit_poucet.svg)](https://rubygems.org/gems/petit_poucet)
+[![ci](https://img.shields.io/github/actions/workflow/status/Sbastien/petit_poucet/ci.yml?branch=main&label=ci)](https://github.com/Sbastien/petit_poucet/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-red.svg)](https://www.ruby-lang.org/)
+[![rails](https://img.shields.io/badge/rails-%3E%3D%207.0-red.svg)](https://rubyonrails.org/)
 
-> *Le petit Pouçet les laissoit crier, sçachant bien par où il reviendroit à la maison ; car en marchant il avoit laissé tomber le long du chemin les petits cailloux blancs qu'il avoit dans ses poches.*
->
-> — Charles Perrault, *Le Petit Poucet* (1697)
+***Breadcrumbs for Rails, the simple way.***
 
-A minimal breadcrumbs gem for Rails. Like the clever boy from the fairy tale who left pebbles to find his way home, this gem helps users navigate back through your application.
+A lightweight, zero-dependency breadcrumbs gem for Ruby on Rails. Simple DSL, controller inheritance, and full view customization — help your users find their way back, one pebble at a time.
+
+## Features
+
+- 🪶 **Zero dependencies** — only Rails required
+- 🎯 **Simple DSL** — declare breadcrumbs in one line
+- 🔗 **Controller inheritance** — child controllers inherit parent breadcrumbs
+- 🎨 **Flexible rendering** — use the built-in helper or full custom views
+- ⚡ **Lazy evaluation** — lambdas for dynamic names and paths
+- 🎛️ **Action filtering** — `only` and `except` options for fine control
+- 📦 **Grouping** — apply filters to multiple breadcrumbs at once
 
 ## Installation
 
@@ -60,6 +71,8 @@ breadcrumb -> { @article.title }
 
 ### Runtime Breadcrumbs
 
+You can also add breadcrumbs at runtime in actions or `before_action` callbacks:
+
 ```ruby
 def show
   @article = Article.find(params[:id])
@@ -68,6 +81,30 @@ def show
 end
 ```
 
+#### Combining Declarative and Runtime
+
+Use declarative breadcrumbs for general structure and runtime for action-specific additions:
+
+```ruby
+class ArticlesController < ApplicationController
+  breadcrumb "Articles", :articles_path
+
+  def show
+    @article = Article.find(params[:id])
+    breadcrumb @article.title, article_path(@article)
+    breadcrumb @article.category.name, category_path(@article.category) if @article.category
+  end
+
+  def edit
+    @article = Article.find(params[:id])
+    breadcrumb @article.title, article_path(@article)
+    breadcrumb "Edit"
+  end
+end
+# show → Articles → My Article → Tech (if category exists)
+# edit → Articles → My Article → Edit
+```
+
 ### View Rendering
 
 #### Simple (built-in helper)
@@ -115,6 +152,145 @@ class AdminController < ApplicationController
 end
 ```
 
+#### Conditional Clearing
+
+Clear inherited breadcrumbs only for specific actions:
+
+```ruby
+class Admin::ArticlesController < AdminController
+  # Start fresh on :new and :create actions only
+  clear_breadcrumbs only: %i[new create]
+  breadcrumb "New Article", only: %i[new create]
+end
+
+class PublicController < ApplicationController
+  # Clear inherited breadcrumbs on all actions except :index
+  clear_breadcrumbs except: :index
+  breadcrumb "Public Section"
+end
+```
+
+### Grouping Breadcrumbs
+
+Use `breadcrumb_group` to apply the same `only`/`except` filters to multiple breadcrumbs:
+
+```ruby
+class ArticlesController < ApplicationController
+  # These breadcrumbs only appear on :edit and :update
+  breadcrumb_group only: %i[edit update] do
+    breadcrumb "Articles", :articles_path
+    breadcrumb -> { @article.title }, -> { article_path(@article) }
+    breadcrumb "Edit"
+  end
+end
+```
+
+#### Nested Groups
+
+Groups can be nested. Options are merged intelligently:
+
+- `:only` uses **intersection** (more restrictive)
+- `:except` uses **union** (cumulative exclusions)
+
+```ruby
+class ArticlesController < ApplicationController
+  breadcrumb_group except: :index do
+    breadcrumb "Articles", :articles_path
+
+    breadcrumb_group only: %i[edit update] do
+      # Appears on :edit and :update, but NOT on :index
+      breadcrumb -> { @article.title }, -> { article_path(@article) }
+    end
+  end
+end
+```
+
+#### Overriding Group Options
+
+Individual breadcrumbs can override group options:
+
+```ruby
+breadcrumb_group only: %i[show edit update] do
+  breadcrumb "Details", :article_path      # Appears on :show, :edit, :update
+  breadcrumb "Edit Form", only: :edit      # Appears only on :edit (intersection)
+end
+```
+
+#### Combining Groups with Regular Breadcrumbs
+
+```ruby
+class ArticlesController < ApplicationController
+  breadcrumb "Home", :root_path                          # Always
+
+  breadcrumb_group only: %i[edit update] do
+    breadcrumb "Edit Section", :edit_article_path        # Only on :edit, :update
+  end
+
+  breadcrumb -> { @article.title }, except: :index       # Except :index
+end
+```
+
+### Complete Example
+
+A typical CRUD controller setup:
+
+```ruby
+class ArticlesController < ApplicationController
+  breadcrumb "Articles", :articles_path
+
+  # Show article title on :show, :edit, :update, :destroy
+  breadcrumb_group only: %i[show edit update destroy] do
+    breadcrumb -> { @article.title }, -> { article_path(@article) }
+  end
+
+  # Add "Edit" crumb on :edit and :update
+  breadcrumb "Edit", only: %i[edit update]
+
+  # Different breadcrumb for new articles
+  breadcrumb "New Article", only: %i[new create]
+
+  def show
+    @article = Article.find(params[:id])
+  end
+
+  # ...
+end
+```
+
+**Result:**
+
+| Action   | Breadcrumbs                          |
+|----------|--------------------------------------|
+| index    | Articles                             |
+| show     | Articles / My Article                |
+| edit     | Articles / My Article / Edit         |
+| new      | Articles / New Article               |
+
+## API Reference
+
+### Controller Class Methods
+
+| Method | Description |
+|--------|-------------|
+| `breadcrumb(name, path = nil, **options)` | Declare a breadcrumb |
+| `clear_breadcrumbs(**options)` | Clear inherited breadcrumbs |
+| `breadcrumb_group(**options, &block)` | Group breadcrumbs with shared options |
+
+### Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `:only` | Show only on these actions | `only: %i[edit update]` |
+| `:except` | Show on all actions except these | `except: :index` |
+
+### Dynamic Values
+
+| Type | Name | Path |
+|------|------|------|
+| String | `"Home"` | `"/path"` |
+| Symbol | `:method_name` | `:path_helper` |
+| Proc | `-> { @model.title }` | `-> { model_path(@model) }` |
+
 ## Requirements
 
 - Ruby >= 3.0
@@ -123,3 +299,13 @@ end
 ## License
 
 MIT
+
+---
+
+## About the Name
+
+> *Le petit Pouçet les laissoit crier, sçachant bien par où il reviendroit à la maison ; car en marchant il avoit laissé tomber le long du chemin les petits cailloux blancs qu'il avoit dans ses poches.*
+>
+> — Charles Perrault, *Le Petit Poucet* (1697)
+
+Named after the French fairy tale "Le Petit Poucet" (Hop-o'-My-Thumb), where a clever boy leaves a trail of pebbles to find his way home.

data/lib/petit_poucet/breadcrumb_group_builder.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PetitPoucet
+  class BreadcrumbGroupBuilder
+    def initialize(controller_class, options, parent_options = nil)
+      @controller_class = controller_class
+      @options = merge_action_options(parent_options, options)
+    end
+
+    def breadcrumb(name, path = nil, **options)
+      merged_options = merge_action_options(@options, options)
+      add_definition(Crumb.new(name, path, **merged_options))
+    end
+
+    def breadcrumb_group(**options, &block)
+      BreadcrumbGroupBuilder.new(@controller_class, options, @options).instance_eval(&block)
+    end
+
+    def clear_breadcrumbs(**options)
+      merged_options = options.empty? ? @options : merge_action_options(@options, options)
+      add_definition(Crumb.new(clear: true, **merged_options))
+    end
+
+    private
+
+    def add_definition(crumb)
+      @controller_class._breadcrumb_definitions = @controller_class._breadcrumb_definitions + [crumb]
+    end
+
+    def merge_action_options(base, override)
+      return override if base.nil? || base.empty?
+      return base if override.nil? || override.empty?
+
+      {}.tap do |result|
+        result[:only] = merge_only(base[:only], override[:only])
+        result[:except] = merge_except(base[:except], override[:except])
+        result.compact!
+      end
+    end
+
+    def merge_only(base_only, override_only)
+      return base_only unless override_only
+      return override_only unless base_only
+
+      # Intersection: more restrictive
+      base_arr = Array(base_only).map(&:to_s)
+      override_arr = Array(override_only).map(&:to_s)
+      (base_arr & override_arr).map(&:to_sym)
+    end
+
+    def merge_except(base_except, override_except)
+      return nil if base_except.nil? && override_except.nil?
+
+      # Union: cumulative exclusions
+      base_arr = Array(base_except).map(&:to_s)
+      override_arr = Array(override_except).map(&:to_s)
+      (base_arr | override_arr).map(&:to_sym)
+    end
+  end
+end

data/lib/petit_poucet/controller_methods.rb

@@ -17,12 +17,40 @@ module PetitPoucet
       # @param options [Hash] Options including :only and :except
       #
       def breadcrumb(name, path = nil, **options)
-        self._breadcrumb_definitions = _breadcrumb_definitions + [Crumb.new(name, path, **options)]
+        _add_breadcrumb_definition(Crumb.new(name, path, **options))
       end
 
       # Clear all inherited breadcrumbs
-      def clear_breadcrumbs
-        self._breadcrumb_definitions = []
+      #
+      # @param options [Hash] Options including :only and :except to conditionally clear
+      #
+      def clear_breadcrumbs(**options)
+        if options.empty?
+          self._breadcrumb_definitions = []
+        else
+          _add_breadcrumb_definition(Crumb.new(clear: true, **options))
+        end
+      end
+
+      # Group multiple breadcrumbs with shared options
+      #
+      # @param options [Hash] Options including :only and :except applied to all breadcrumbs in block
+      # @yield Block containing breadcrumb declarations
+      #
+      # @example
+      #   breadcrumb_group only: %i[index show edit] do
+      #     breadcrumb 'Home', '/'
+      #     breadcrumb 'Section', '/section'
+      #   end
+      #
+      def breadcrumb_group(**options, &block)
+        BreadcrumbGroupBuilder.new(self, options).instance_eval(&block)
+      end
+
+      private
+
+      def _add_breadcrumb_definition(crumb)
+        self._breadcrumb_definitions = _breadcrumb_definitions + [crumb]
       end
     end
 
@@ -52,7 +80,12 @@ module PetitPoucet
     private
 
     def resolve_breadcrumbs
-      crumbs = _breadcrumb_definitions.select { |c| c.applies_to_action?(action_name) }
+      crumbs = []
+      _breadcrumb_definitions.each do |crumb|
+        next unless crumb.applies_to_action?(action_name)
+
+        crumb.clear? ? crumbs.clear : crumbs << crumb
+      end
       crumbs += @runtime_breadcrumbs || []
       crumbs.map { |crumb| { name: crumb.resolve_name(self), path: crumb.resolve_path(self) } }
     end

data/lib/petit_poucet/crumb.rb

@@ -4,8 +4,9 @@ module PetitPoucet
   class Crumb
     attr_reader :name, :path
 
-    def initialize(name, path = nil, **options)
+    def initialize(name = nil, path = nil, clear: false, **options)
       @name = name
+      @clear = clear
 
       if path.is_a?(Hash)
         options = path
@@ -18,6 +19,10 @@ module PetitPoucet
       @except_actions = options[:except] && Array(options[:except]).map(&:to_s)
     end
 
+    def clear?
+      @clear
+    end
+
     def resolve_name(context)
       case name
       when Proc then context.instance_exec(&name)

data/lib/petit_poucet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PetitPoucet
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 end

data/lib/petit_poucet.rb

@@ -3,6 +3,7 @@
 require_relative 'petit_poucet/version'
 require_relative 'petit_poucet/crumb'
 require_relative 'petit_poucet/crumb_presenter'
+require_relative 'petit_poucet/breadcrumb_group_builder'
 require_relative 'petit_poucet/controller_methods'
 require_relative 'petit_poucet/view_helpers'
 require_relative 'petit_poucet/railtie' if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: petit_poucet
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Sébastien Loyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-04 00:00:00.000000000 Z
+date: 2025-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -38,7 +38,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-description: Minimal breadcrumbs gem with declarative DSL and action filtering
+description: A zero-dependency breadcrumbs gem for Rails with simple DSL, controller
+  inheritance, and flexible view rendering.
 email:
 executables: []
 extensions: []
@@ -48,6 +49,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/petit_poucet.rb
+- lib/petit_poucet/breadcrumb_group_builder.rb
 - lib/petit_poucet/controller_methods.rb
 - lib/petit_poucet/crumb.rb
 - lib/petit_poucet/crumb_presenter.rb
@@ -61,6 +63,8 @@ metadata:
   homepage_uri: https://github.com/Sbastien/petit_poucet
   source_code_uri: https://github.com/Sbastien/petit_poucet
   changelog_uri: https://github.com/Sbastien/petit_poucet/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/Sbastien/petit_poucet
+  bug_tracker_uri: https://github.com/Sbastien/petit_poucet/issues
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -80,5 +84,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Modern breadcrumbs DSL for Rails
+summary: Lightweight breadcrumbs gem for Ruby on Rails
 test_files: []