keynote 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: bbd02a5e8d588001102132e7864b294e34290700
-  data.tar.gz: d8db8a485b076d070774031959cecbc2f0b9fb68
+SHA256:
+  metadata.gz: 961b8bbb609c798ba7dd9e9d2896132bc87856f2059724a3cf2be80596cd8be1
+  data.tar.gz: 3a242df538467281e4a5df928e4fc1eab7ffad18a715813b8abc86ec5a815565
 SHA512:
-  metadata.gz: 2033a7f5c59e895ac0d8f31202591f02f8d4f5f750203b940696f029968a14c0f59d0d8bba990f7f3ef95bb39358605b961326b869b074366210411ef7b80c9a
-  data.tar.gz: d683f2f2259fbff0ad2ab280ce5300093f25ed4e6bc68a13a5901a7d422fe0764a61dd50f6fb74de5babe3ed582772d47c224d16262218d9000f40a9506797e9
+  metadata.gz: 3575f94138d3ccf5a0f45dce0137d616dc79c967753b616f64e02152eb4ed3e5dca8ae91ace4f95206ae082d9a3591b5d39826d2ca7073045dc22331d5a27a2d
+  data.tar.gz: 24ed666d1ee71ebf9e14cee38faf41cf51ad6000260cd695ec3eabd9ab1095270d8588fcdc0cd9d3aff86bff1578864d6e52f92519974ef6717c2e421c883069

data/CHANGELOG.md

@@ -1,58 +1,106 @@
+# Change log
+
+## v2.0.0 (2025-01-10)
+
+- Update the inline template API to pass source as string instead of parsing comments. [@palkan][]
+
+  ```rb
+  # BEFORE:
+  def method_with_a_template
+    a = "foo"
+
+    erb
+    # <div><%= a %></div>
+  end
+
+  # AFTER:
+  def method_with_a_template
+    a = "foo"
+
+    erb(a:) { "<div><%= a %></div>" }
+  end
+  ```
+
+  This change makes inline templates less magical, IDE-friendly, and much faster.
+
+- **Ruby 3+** and **Rails 7+** are required. [@palkan][]
+
+## v1.1.1
+
+- Rumble: Fix passing `true` as an attribute value, which was broken by the
+  escaping changes in v1.0.0. [@igas][]
+
 ## v1.1.0
-* Rumble: Fix bug in v1.0.0 that caused an exception if the user passed a `nil`
+
+- Rumble: Fix bug in v1.0.0 that caused an exception if the user passed a `nil`
   value for an attribute.
-* Rumble: Add support for `aria` attr hashes, behaving the same way as `data`.
+- Rumble: Add support for `aria` attr hashes, behaving the same way as `data`.
 
 ## v1.0.0
-* Add support for Rails 5.1.
-* Fix all Ruby warnings generated by Keynote itself.
-* Rumble: Always escape quotation marks in HTML attributes, even if the string
+
+- Add support for Rails 5.1.
+- Fix all Ruby warnings generated by Keynote itself.
+- Rumble: Always escape quotation marks in HTML attributes, even if the string
   is already marked as HTML-safe.
-* Rumble: Allow user to pass in a `data` hash to generate data attributes.
-* Rumble: Allow user to pass in an array value for an attribute, which will be
+- Rumble: Allow user to pass in a `data` hash to generate data attributes.
+- Rumble: Allow user to pass in an array value for an attribute, which will be
   joined by spaces.
 
 ## v0.3.1
-* Add support for Rails 5.0. (@dra)
+
+- Add support for Rails 5.0. [@dra][]
 
 ## v0.3.0
-* Drop support for Rails 3.0 and Ruby 1.9.2; add support for Rails 4.2.
-* Drop support for MiniTest::Rails versions older than 2.0; add support for 2.0
-  and higher. (@kirs)
+
+- Drop support for Rails 3.0 and Ruby 1.9.2; add support for Rails 4.2.
+- Drop support for MiniTest::Rails versions older than 2.0; add support for 2.0
+  and higher. [@kirs][]
 
 ## v0.2.3
-* Allow user to pass the string version of the presenter name into
+
+- Allow user to pass the string version of the presenter name into
   `Keynote.present` as an alternative to passing a symbol. This makes it less
   awkward to use namespaced presenters, but it does remove the possibility of
   defining a `StringPresenter` and using it with code like
   `k('some string').format_as_markdown`. It seems unlikely that anyone is
-  actually doing that though. (@outpunk)
-* Update RSpec integration to not print deprecation warnings with RSpec 3.
-  (@DarthSim)
+  actually doing that though. [@outpunk][]
+- Update RSpec integration to not print deprecation warnings with RSpec 3.
+  [@DarthSim][]
 
 ## v0.2.2
-* Fix another RSpec integration bug, which happened in cases where the app's
+
+- Fix another RSpec integration bug, which happened in cases where the app's
   Gemfile included rspec-rails but not the rspec gem itself.
-* Fix a bug in the generation of specs for zero-arg presenters.
+- Fix a bug in the generation of specs for zero-arg presenters.
 
 ## v0.2.1
-* Update configuration to test across MRI 1.9.2/1.9.3/2.0.0/2.1.0, Rubinius,
+
+- Update configuration to test across MRI 1.9.2/1.9.3/2.0.0/2.1.0, Rubinius,
   JRuby, Rails 3.0/3.1/3.2/4.0/4.1.
-* Fix issue #6, in which the order of dependencies in the Gemfile could keep
+- Fix issue #6, in which the order of dependencies in the Gemfile could keep
   Keynote's RSpec integration from loading correctly.
 
 ## v0.2.0
-* Add `Keynote::Inline`, a module that presenters can extend to enable inline
+
+- Add `Keynote::Inline`, a module that presenters can extend to enable inline
   templating in any language supported by Rails.
-* Presenters now have a `use_html_5_tags` class method that adds a more
+- Presenters now have a `use_html_5_tags` class method that adds a more
   complete set of Rumble tag methods to the class.
-* Add `object_names` class method to presenters, returning an array of the
+- Add `object_names` class method to presenters, returning an array of the
   symbols that have been passed into the `presents` method.
-* Add an implementation of the `present`/`k` method that's available in test
+- Add an implementation of the `present`/`k` method that's available in test
   cases. Update test generators accordingly.
-* Update minitest-rails integration to be compatible with the newest
+- Update minitest-rails integration to be compatible with the newest
   version of minitest-rails (on Rails 3.0, 3.1, 3.2, and 4.0).
 
 ## v0.1.3
-* Add block form of `present`. If you pass a block into a `present` call, it
+
+- Add block form of `present`. If you pass a block into a `present` call, it
   yields the presenter.
+
+[@palkan]: https://github.com/palkan
+[@igas]: https://github.com/igas
+[@dra]: https://github.com/dra
+[@kirs]: https://github.com/kirs
+[@outpunk]: https://github.com/outpunk
+[@DarthSim]: https://github.com/DarthSim

data/{LICENSE → LICENSE.txt}

@@ -1,9 +1,4 @@
-Copyright (c) 2012 Ryan Fitzgerald
-
-Includes a modified version of Rumble, which is (c) 2011 Magnus Holm.
-
-Some Rails integration code inspired by Draper, which is (c) 2011-2012 Jeff
-Casimir and other contributors.
+Copyright (c) 2025 Ryan Fitzgerald
 
 MIT License
 
@@ -25,3 +20,4 @@ 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

@@ -1,9 +1,10 @@
-# Keynote
+[![Gem Version](https://badge.fury.io/rb/keynote.svg)](https://rubygems.org/gems/keynote)
+[![Build](https://github.com/evilmartians/keynote/workflows/Build/badge.svg)](https://github.com/evilmartians/keynote/actions)
 
-*Flexible presenters for Rails.*
+# Keynote
 
-[![Travis CI](https://api.travis-ci.org/rf-/keynote.png)](https://travis-ci.org/rf-/keynote/builds)
-[![Code Climate](https://codeclimate.com/github/rf-/keynote.png)](https://codeclimate.com/github/rf-/keynote)
+> [!TIP]
+> Flexible presenters for Rails.
 
 A presenter is an object that encapsulates view logic. Like Rails helpers,
 presenters help you keep complex logic out of your templates.
@@ -11,16 +12,30 @@ presenters help you keep complex logic out of your templates.
 Keynote provides a consistent interface for defining and instantiating
 presenters.
 
+## Requirements
+
+- Ruby >= 3.0.0
+- Rails >= 7.0
+
+For older Ruby and Rails versions, you can use Keynote <2.0.
+
 ## Usage
 
+Add Keynote to your Gemfile:
+
+```ruby
+gem "keynote", "~> 2.0"
+```
+
+Don't forget to run `bundle install`.
+
 ### The basic idea
 
 A simple case is making a presenter that's named after a model class and holds
 helper methods related to that model.
 
-``` ruby
+```ruby
 # app/presenters/user_presenter.rb
-
 class UserPresenter < Keynote::Presenter
   presents :user
 
@@ -29,7 +44,7 @@ class UserPresenter < Keynote::Presenter
   end
 
   def profile_link
-    link_to user, display_name, data: { user_id: user.id }
+    link_to user, display_name, data: {user_id: user.id}
   end
 end
 ```
@@ -55,22 +70,25 @@ Keynote looks for a class called `UserPresenter`.
 
 ### Generating HTML
 
-To make it easier to generate slightly more complex chunks of HTML, Keynote
-includes a modified version of Magnus Holm's [Rumble](https://github.com/judofyr/rumble)
+To make it easier to generate slightly more complex chunks of HTML, Keynote provides several ways to generate HTML fragments.
+
+#### Using `build_html`
+
+Keynote includes a modified version of Magnus Holm's [Rumble](https://github.com/judofyr/rumble)
 library. Rumble gives us a simple block-based syntax for generating HTML
 fragments. Here's a small example:
 
-``` ruby
+```ruby
 build_html do
   div id: :content do
-    h1 'Hello World', class: :main
+    h1 "Hello World", class: :main
   end
 end
 ```
 
 Becomes:
 
-``` html
+```html
 <div id="content">
   <h1 class="main">Hello World</h1>
 </div>
@@ -81,6 +99,32 @@ to the `build_html` method. The `build_html` method returns a safe string. See
 [the documentation for `Keynote::Rumble`](http://rubydoc.info/gems/keynote/Keynote/Rumble)
 for more information.
 
+#### Using inlined partials
+
+You can extend your presenter class with the `Keynote::Inline` module to enable inline templating in any template language supported by Rails. This is useful for small, self-contained templates that don't need to be extracted into separate files.
+
+```ruby
+# app/presenters/user_presenter.rb
+class UserPresenter < Keynote::Presenter
+  presents :user
+
+  include Keynote::Inline
+  # To user Haml or Slim, enabled them explicitly
+  # inline :haml, :slim
+
+  def profile_link
+    erb do
+      <<~ERB
+        <div class="profile_link">
+          <%= link_to user, display_name, data: { user_id: user.id } %>
+          <i class="fa-user"></i>
+        </div>
+      ERB
+    end
+  end
+end
+```
+
 ### A more complex example
 
 Let's add to our original example by introducing a named presenter. In addition
@@ -158,33 +202,76 @@ end
 You can also generate prefixed methods like `user_first_name` by passing
 `prefix: true` to the `delegate` method.
 
+## Testing
+
+Testing a Keynote presenter is similar to using it in views or controllers. You
+can test presenters with RSpec, Test::Unit, MiniTest, or MiniTest::Unit.
+
+### RSpec
+
+Your test files should be in `spec/presenters` or labeled with
+[`type: :presenter` metadata].
+
+Here's an example:
+
+```ruby
+# spec/presenters/user_presenter_spec.rb
+
+RSpec.describe UserPresenter do
+  describe "#display_name" do
+    it "returns the name of the user" do
+      user = User.new(first_name: "Alice", last_name: "Smith")
+
+      expect(present(user).display_name).to eq("Alice Smith")
+    end
+  end
+end
+```
+
+### MiniTest
+
+Your test classes should inherit from Keynote::TestCase.
+
+```ruby
+class UserPresenterTest < Keynote::TestCase
+  setup do
+    user = User.new(first_name: "Alice", last_name: "Smith")
+    @presenter = present(user)
+  end
+
+  test "display name" do
+    assert_equal @presenter.display_name, "Alice Smith"
+  end
+end
+```
+
 ## Rationale
 
-### Why use presenters or decorators at all?
+### Why use presenters or decorators at all
 
 The main alternative is to use helpers. Helpers are fine for many use cases --
 Rails' built-in tag and form helpers are great. They have some drawbacks,
 though:
 
-* Every helper method you write gets mixed into the same view object as the
+- Every helper method you write gets mixed into the same view object as the
   built-in Rails helpers, URL generators, and all the other junk that comes
   along with `ActionView::Base`. In a freshly-generated Rails project:
 
   ```ruby
-  >> ApplicationController.new.view_context.public_methods.count
-  => 318
-  >> ApplicationController.new.view_context.private_methods.count
-  => 119
+  ApplicationController.new.view_context.public_methods.count
+  # => 318
+  ApplicationController.new.view_context.private_methods.count
+  # => 119
   ```
 
-* Helpers can't have state that isn't "global" relative to the view, which
+- Helpers can't have state that isn't "global" relative to the view, which
   can make it hard to write helpers that work together.
 
-* By default, every helper is available in every view. This makes it difficult
+- By default, every helper is available in every view. This makes it difficult
   to set boundaries between different parts of your app and organize your view
   code cleanly.
 
-### Why not use decorators?
+### Why not use decorators
 
 The biggest distinction between Keynote and similar libraries like [Draper] and
 [DisplayCase] is that Keynote presenters aren't decorators – undefined method
@@ -193,17 +280,17 @@ calls don't fall through to an underlying model.
 Applying the Decorator pattern to generating views is a reasonable thing to do.
 However, this practice also has some downsides.
 
-* Decorators make the most sense when there's exactly one object that's
+- Decorators make the most sense when there's exactly one object that's
   relevant to the methods you want to encapsulate. They're less helpful when
   you want to do things like define a class whose responsibility is to help
   render a specific part of your user interface, which may involve bringing in
   data from multiple models or collections.
 
-* When reading code that uses decorators, it often isn't obvious if a given
+- When reading code that uses decorators, it often isn't obvious if a given
   method is defined on the decorator or the underlying model, especially when
   the decorator is applied in the controller instead of the view.
 
-* Passing decorated models between controllers and views can make it unclear
+- Passing decorated models between controllers and views can make it unclear
   whether a view (especially a nested partial) depends on a model having some
   specific decorator applied to it. This makes refactoring view and decorator
   code harder than it needs to be.
@@ -214,7 +301,7 @@ Keynote doesn't automatically generate presenters when you generate models or
 resources. To generate a presenter, you can use the `presenter` generator,
 like so:
 
-``` bash
+```sh
 $ rails g presenter FooBar foo bar
       create  app/presenters/foo_bar_presenter.rb
       create  spec/presenters/foo_bar_presenter_spec.rb
@@ -223,34 +310,19 @@ $ rails g presenter FooBar foo bar
 That project uses RSpec, but the generator can also create test files for
 Test::Unit or MiniTest::Rails if applicable.
 
-## Compatibility
-
-Keynote is supported on Rails 3.1 through 5.1. Keynote presenters are testable
-with Test::Unit, RSpec, and MiniTest::Rails (>= 2.0).
-
-If you find problems with any of the above integrations, please open an issue.
+## Contributing
 
-## Development
+Bug reports and pull requests are welcome on GitHub at [https://github.com/evilmartians/keynote](https://github.com/evilmartians/keynote).
 
-This repo uses [Roadshow] to generate a [Docker Compose] file for each
-supported version of Rails (with a compatible version of Ruby for each one).
+For gem development, clone the repo and run `bundle install` to install the dependencies. Then, run `bundle exec rake` to run the tests.
 
-To run specs across all versions, you can either [get the Roadshow tool] and
-run `roadshow run`, or use Docker Compose directly:
-
-```
-$ for fn in scenarios/*.docker-compose-yml; do docker-compose -f $fn run --rm scenario; done
-```
+(Optionally) Run `bundle exec lefthook install` to configure git hooks (so you never miss linter complaints before opening a PR).
 
-To update the set of scenarios, edit `scenarios.yml` and run `roadshow
-generate`, although the Gemfiles in the `scenarios` directory need to be
-maintained manually.
+## License
 
-Feel free to submit pull requests according to the usual conventions for Ruby
-projects.
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
 [DisplayCase]: https://github.com/objects-on-rails/display-case
 [Draper]: https://github.com/drapergem/draper
 [Roadshow]: https://github.com/rf-/roadshow
-[Docker Compose]: https://docs.docker.com/compose/
-[get the Roadshow tool]: https://github.com/rf-/roadshow/releases
+[`type: :presenter` metadata]: https://relishapp.com/rspec/rspec-rails/docs/directory-structure

data/lib/generators/presenter_generator.rb

@@ -1,34 +1,29 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 
 module Rails::Generators
   class PresenterGenerator < Rails::Generators::NamedBase
     desc "This generator creates a Keynote::Presenter subclass in " \
         "app/presenters."
 
-    argument :targets, :type => :array, :default => []
+    argument :targets, type: :array, default: []
 
-    check_class_collision :suffix => 'Presenter'
-    source_root File.expand_path('../templates', __FILE__)
+    check_class_collision suffix: "Presenter"
+    source_root File.expand_path("../templates", __FILE__)
 
     def create_presenter_file
-      template 'keynote_presenter.rb',
-        File.join('app/presenters', class_path, "#{file_name}_presenter.rb")
+      template "keynote_presenter.rb",
+        File.join("app/presenters", class_path, "#{file_name}_presenter.rb")
     end
 
     def create_test_file
       case Rails.application.config.generators.rails[:test_framework]
       when :rspec
-        template 'keynote_rspec.rb', rspec_path
-      when :test_unit
-        # In Rails 4 this is kind of a weird place to generate tests into.
-        # Unfortunately it isn't really fixable without changing the Rails
-        # test tasks, so that's a TODO.
-        template 'keynote_test_unit.rb', test_unit_path
+        template "keynote_rspec.rb", rspec_path
       when :mini_test
         if Rails.application.config.generators.mini_test[:spec]
-          template 'keynote_mini_test_spec.rb', mini_test_path
+          template "keynote_mini_test_spec.rb", mini_test_path
         else
-          template 'keynote_mini_test_unit.rb', mini_test_path
+          template "keynote_mini_test_unit.rb", mini_test_path
         end
       end
     end
@@ -37,29 +32,26 @@ module Rails::Generators
 
     def rspec_path
       File.join(
-        'spec/presenters', class_path, "#{file_name}_presenter_spec.rb")
-    end
-
-    def test_unit_path
-      File.join(
-        'test/unit/presenters', class_path, "#{file_name}_presenter_test.rb")
+        "spec/presenters", class_path, "#{file_name}_presenter_spec.rb"
+      )
     end
 
     def mini_test_path
       File.join(
-        'test/presenters', class_path, "#{file_name}_presenter_test.rb")
+        "test/presenters", class_path, "#{file_name}_presenter_test.rb"
+      )
     end
 
     def presenter_name_and_target_list
-      [presenter_name, *target_names].join(', ')
+      [presenter_name, *target_names].join(", ")
     end
 
     def target_list
-      target_names.join(', ')
+      target_names.join(", ")
     end
 
     def presenter_name
-      class_name.sub(/Presenter$/, '').underscore.to_sym.inspect
+      class_name.sub(/Presenter$/, "").underscore.to_sym.inspect
     end
 
     def target_names

data/lib/keynote/cache.rb

@@ -1,4 +1,4 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 
 module Keynote
   # `Keynote::Cache` memoizes presenter instances, reducing the overhead of

data/lib/keynote/controller.rb

@@ -1,4 +1,4 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 
 module Keynote
   # `Keynote::Controller` is mixed into `ActionController::Base` and
@@ -7,9 +7,8 @@ module Keynote
   module Controller
     # Instantiate a presenter.
     # @see Keynote.present
-    def present(*objects, &blk)
-      Keynote.present(view_context, *objects, &blk)
-    end
-    alias k present
+    def present(...) = Keynote.present(view_context, ...)
+
+    alias_method :k, :present
   end
 end

data/lib/keynote/core.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Keynote is a library for defining and instantiating presenters,
+# objects that encapsulate view logic.
+#
+# @see file:README.md
+module Keynote
+  class << self
+    # Create or retrieve a presenter wrapping zero or more objects.
+    # If a block is given, yield the presenter into it.
+    #
+    # The first parameter is a Rails view context, but you'll usually access
+    # this method through `Keynote::Helper#present`,
+    # `Keynote::Controller#present`, or `Keynote::Presenter#present`, all of
+    # which handle the view context parameter automatically.
+    #
+    # @see Keynote::Helper#present
+    # @see Keynote::Controller#present
+    # @see Keynote::Presenter#present
+    #
+    # @overload present(view, *objects)
+    #   Return a presenter wrapping the given objects. The type of the
+    #   presenter will be inferred from the type of the first object.
+    #   @example
+    #     present(view, MyModel.new)           # => #<MyModelPresenter:0x0001>
+    #   @param [ActionView::Base] view
+    #   @param [Array] objects
+    #   @return [Keynote::Presenter]
+    #
+    # @overload present(view, presenter_name, *objects)
+    #   Return a presenter wrapping the given objects. The type of the
+    #   presenter is specified in underscore form by the first parameter.
+    #   @example
+    #     present(view, :foo_bar, MyModel.new) # => #<FooBarPresenter:0x0002>
+    #   @param [ActionView::Base] view
+    #   @param [Symbol, String] presenter_name
+    #   @param [Array] objects
+    #   @return [Keynote::Presenter]
+    #
+    def present(view, *objects)
+      name = if objects[0].is_a?(Symbol) || objects[0].is_a?(String)
+        objects.shift
+      else
+        presenter_name_from_object(objects[0])
+      end
+
+      Cache.fetch(name, view, *objects) do
+        presenter_from_name(name).new(view, *objects).tap do |presenter|
+          yield presenter if block_given?
+        end
+      end
+    end
+
+    private
+
+    def presenter_name_from_object(object)
+      object.class.to_s.underscore
+    end
+
+    def presenter_from_name(name)
+      "#{name.to_s.camelize}Presenter".constantize
+    end
+  end
+end

data/lib/keynote/helper.rb

@@ -1,4 +1,4 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 
 module Keynote
   # `Keynote::Helper` is mixed into `ActionView::Base`, providing a `present`
@@ -6,9 +6,8 @@ module Keynote
   module Helper
     # Instantiate a presenter.
     # @see Keynote.present
-    def present(*objects, &blk)
-      Keynote.present(self, *objects, &blk)
-    end
-    alias k present
+    def present(...) = Keynote.present(self, ...)
+
+    alias_method :k, :present
   end
 end