petit_poucet 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31a0dd9277ecdaa4109bc2baaf3d8a7bc7c7e63ddc25d04986b384476d2b2129
+  data.tar.gz: 11148aa356349a3d75ff866b972ba628f6d5d389df322aaee6316b06ba87792d
+SHA512:
+  metadata.gz: 41d0d30be7ca055999c3901aa0704323e15329d87d709eed97e12a840f5b9ee439a53cffc279f1a5a9184354ed588d9d8b279bfa34e47e78a60e0527e6a895a7
+  data.tar.gz: de911c4ee152f4ea74804b4b9c5f930d306189fde6cd1c021294a73a1381d708a09aaa88fcbaceb4f507f0397bb0b6cba765ba5074a959fd2b52f9acbdeb2412

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2025-12-03
+
+### Added
+
+- Declarative `breadcrumb` DSL for controllers (class and instance level)
+- Action filtering with `only:` and `except:` options
+- Dynamic breadcrumbs with lambdas and symbols
+- `breadcrumb_trail` view helper with `CrumbPresenter`
+- `current?` method to identify the last breadcrumb
+- `render_breadcrumbs` simple view helper with customizable separator and class
+- `clear_breadcrumbs` to reset inherited breadcrumbs
+- Rails 7.0+ and Ruby 3.0+ support

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sébastien Loyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,125 @@
+# 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)
+
+> *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)
+
+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.
+
+## Installation
+
+```ruby
+gem "petit_poucet"
+```
+
+## Usage
+
+### Controller
+
+```ruby
+class ApplicationController < ActionController::Base
+  breadcrumb -> { t("home") }, :root_path
+end
+
+class ArticlesController < ApplicationController
+  breadcrumb "Articles", :articles_path
+  breadcrumb -> { @article.title }, only: [:show, :edit, :update]
+
+  def show
+    @article = Article.find(params[:id])
+  end
+end
+```
+
+### DSL Options
+
+```ruby
+# Static
+breadcrumb "Dashboard", :dashboard_path
+
+# Dynamic name
+breadcrumb -> { t("breadcrumbs.home") }, :root_path
+
+# Dynamic path
+breadcrumb "Profile", -> { user_path(current_user) }
+
+# Action filtering
+breadcrumb "Edit", :edit_article_path, only: [:edit, :update]
+breadcrumb "Details", :articles_path, except: :index
+
+# Action filtering without path
+breadcrumb "Current", only: :show
+
+# No link (current page)
+breadcrumb -> { @article.title }
+```
+
+### Runtime Breadcrumbs
+
+```ruby
+def show
+  @article = Article.find(params[:id])
+  breadcrumb @article.title, article_path(@article)
+  breadcrumb "Details"  # No link
+end
+```
+
+### View Rendering
+
+#### Simple (built-in helper)
+
+```erb
+<%= render_breadcrumbs %>
+<%# => <nav class="breadcrumb"><a href="/">Home</a> / Articles / My Article</nav> %>
+
+<%= render_breadcrumbs(class: "my-breadcrumb", separator: " > ") %>
+```
+
+#### Custom (full control)
+
+```erb
+<nav aria-label="Breadcrumb">
+  <ol>
+    <% breadcrumb_trail do |crumb| %>
+      <li>
+        <% if crumb.current? %>
+          <%= crumb.name %>
+        <% else %>
+          <%= link_to crumb.name, crumb.path %>
+        <% end %>
+      </li>
+    <% end %>
+  </ol>
+</nav>
+```
+
+### CrumbPresenter
+
+| Method     | Description              |
+|------------|--------------------------|
+| `name`     | Display text             |
+| `path`     | URL (can be nil)         |
+| `current?` | `true` if last breadcrumb |
+| `to_s`     | Returns `name`           |
+
+### Clearing Inherited Breadcrumbs
+
+```ruby
+class AdminController < ApplicationController
+  clear_breadcrumbs
+  breadcrumb "Admin", :admin_root_path
+end
+```
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 7.0
+
+## License
+
+MIT

data/lib/petit_poucet/controller_methods.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PetitPoucet
+  module ControllerMethods
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_breadcrumb_definitions, default: []
+      helper_method :breadcrumbs if respond_to?(:helper_method)
+    end
+
+    class_methods do
+      # Declare a breadcrumb at the class level
+      #
+      # @param name [String, Symbol, Proc] The breadcrumb label
+      # @param path [String, Symbol, Proc, nil] The breadcrumb URL
+      # @param options [Hash] Options including :only and :except
+      #
+      def breadcrumb(name, path = nil, **options)
+        self._breadcrumb_definitions = _breadcrumb_definitions + [Crumb.new(name, path, **options)]
+      end
+
+      # Clear all inherited breadcrumbs
+      def clear_breadcrumbs
+        self._breadcrumb_definitions = []
+      end
+    end
+
+    # Add a breadcrumb dynamically within an action
+    #
+    # @param name [String, Proc] The breadcrumb label
+    # @param path [String, nil] The breadcrumb URL
+    #
+    def breadcrumb(name, path = nil)
+      @runtime_breadcrumbs ||= []
+      @runtime_breadcrumbs << Crumb.new(name, path)
+    end
+
+    # Clear runtime breadcrumbs
+    def clear_breadcrumbs
+      @runtime_breadcrumbs = []
+    end
+
+    # Get all resolved breadcrumbs for the current action
+    #
+    # @return [Array<Hash>] Array of { name:, path: } hashes
+    #
+    def breadcrumbs
+      @breadcrumbs ||= resolve_breadcrumbs
+    end
+
+    private
+
+    def resolve_breadcrumbs
+      crumbs = _breadcrumb_definitions.select { |c| c.applies_to_action?(action_name) }
+      crumbs += @runtime_breadcrumbs || []
+      crumbs.map { |crumb| { name: crumb.resolve_name(self), path: crumb.resolve_path(self) } }
+    end
+  end
+end

data/lib/petit_poucet/crumb.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PetitPoucet
+  class Crumb
+    attr_reader :name, :path
+
+    def initialize(name, path = nil, **options)
+      @name = name
+
+      if path.is_a?(Hash)
+        options = path
+        @path = nil
+      else
+        @path = path
+      end
+
+      @only_actions = options[:only] && Array(options[:only]).map(&:to_s)
+      @except_actions = options[:except] && Array(options[:except]).map(&:to_s)
+    end
+
+    def resolve_name(context)
+      case name
+      when Proc then context.instance_exec(&name)
+      when Symbol then context.public_send(name)
+      else name.to_s
+      end
+    end
+
+    def resolve_path(context)
+      return nil if path.nil?
+
+      case path
+      when Proc then context.instance_exec(&path)
+      when Symbol then context.public_send(path)
+      else path.to_s
+      end
+    end
+
+    def applies_to_action?(action_name)
+      return false if @only_actions && !@only_actions.include?(action_name)
+      return false if @except_actions&.include?(action_name)
+
+      true
+    end
+  end
+end

data/lib/petit_poucet/crumb_presenter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PetitPoucet
+  # Presenter for a single breadcrumb in views
+  #
+  # @example
+  #   crumb.name      # => "Home"
+  #   crumb.path      # => "/"
+  #   crumb.current?  # => false
+  #
+  class CrumbPresenter
+    attr_reader :name, :path
+
+    def initialize(name:, path:, current:)
+      @name = name
+      @path = path
+      @current = current
+    end
+
+    def current?
+      @current
+    end
+
+    def to_s
+      name
+    end
+  end
+end

data/lib/petit_poucet/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PetitPoucet
+  class Railtie < Rails::Railtie
+    initializer 'petit_poucet.configure' do
+      ActiveSupport.on_load(:action_controller) do
+        include PetitPoucet::ControllerMethods
+      end
+
+      ActiveSupport.on_load(:action_view) do
+        include PetitPoucet::ViewHelpers
+      end
+    end
+  end
+end

data/lib/petit_poucet/version.rb

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

data/lib/petit_poucet/view_helpers.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module PetitPoucet
+  module ViewHelpers
+    # Iterate over breadcrumbs with full control over rendering
+    #
+    # @yield [crumb] Block called for each breadcrumb
+    # @yieldparam crumb [CrumbPresenter] Presenter with name, path, current?
+    # @return [Array<CrumbPresenter>] All breadcrumbs if no block given
+    #
+    # @example Without block
+    #   breadcrumb_trail.each { |crumb| ... }
+    #
+    # @example With block
+    #   breadcrumb_trail do |crumb|
+    #     concat link_to(crumb.name, crumb.path) unless crumb.current?
+    #   end
+    #
+    def breadcrumb_trail(&block)
+      crumbs = breadcrumbs.each_with_index.map do |crumb, index|
+        CrumbPresenter.new(
+          name: crumb[:name],
+          path: crumb[:path],
+          current: index == breadcrumbs.size - 1
+        )
+      end
+
+      return crumbs unless block_given?
+
+      crumbs.each(&block)
+    end
+
+    # Simple default renderer for breadcrumbs
+    #
+    # @param options [Hash] Rendering options
+    # @option options [String] :class CSS class for the container ('breadcrumb')
+    # @option options [String] :separator Separator between crumbs (' / ')
+    #
+    # @return [ActiveSupport::SafeBuffer, nil] HTML or nil if no breadcrumbs
+    #
+    # @example Default rendering
+    #   render_breadcrumbs
+    #   # => <nav class="breadcrumb">Home / Articles / My Article</nav>
+    #
+    # @example Custom options
+    #   render_breadcrumbs(class: 'custom-breadcrumb', separator: ' > ')
+    #
+    def render_breadcrumbs(options = {})
+      return if breadcrumbs.empty?
+
+      css_class = options[:class] || 'breadcrumb'
+      separator = options[:separator] || ' / '
+
+      items = breadcrumb_trail.map do |crumb|
+        if crumb.path.present? && !crumb.current?
+          link_to(crumb.name, crumb.path)
+        else
+          crumb.name
+        end
+      end
+
+      content_tag(:nav, safe_join(items, separator.html_safe), class: css_class)
+    end
+  end
+end

data/lib/petit_poucet.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'petit_poucet/version'
+require_relative 'petit_poucet/crumb'
+require_relative 'petit_poucet/crumb_presenter'
+require_relative 'petit_poucet/controller_methods'
+require_relative 'petit_poucet/view_helpers'
+require_relative 'petit_poucet/railtie' if defined?(Rails::Railtie)
+
+module PetitPoucet
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: petit_poucet
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sébastien Loyer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Minimal breadcrumbs gem with declarative DSL and action filtering
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/petit_poucet.rb
+- lib/petit_poucet/controller_methods.rb
+- lib/petit_poucet/crumb.rb
+- lib/petit_poucet/crumb_presenter.rb
+- lib/petit_poucet/railtie.rb
+- lib/petit_poucet/version.rb
+- lib/petit_poucet/view_helpers.rb
+homepage: https://github.com/Sbastien/petit_poucet
+licenses:
+- MIT
+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
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Modern breadcrumbs DSL for Rails
+test_files: []