slotify 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3528c82a3e01b2acc454f5df4c8081f19157e975a2e2ddaa46f56dadc565426f
-  data.tar.gz: e9660ecb767e9ec12156eb3e878f10cdf9fe74c8b67b9fbc574fa64cae1f5f1a
+  metadata.gz: 7901ad71acf99111a450667e96a494becbfc55d78c62ab2314b7c3b8dae7e588
+  data.tar.gz: 73ef165ade4d766b69ef68cbba336bf488991e452038f751d3e5fb2f82c34bf5
 SHA512:
-  metadata.gz: fe68d4ff07cbc1a12cc69937bb0da7af4080082504226f7dd9c63a8f4b35461460671265ca09745a9899e6e49ac5aab0c377a83d795a2547eb423255907aa84d
-  data.tar.gz: a189cd09e36a1eab05de32a1c62f953acbe72dcca1ed64c0dd058002ded2f8da2d828e95e0ba0b7865a29d3cac4c58a1cc9c7ad45679ce87684a8edfe03e1032
+  metadata.gz: 906ce11515dcb698273445333d273233e96b9006454714b8d17d8a034f38fd333ef649c4d196e21d403e93ed1bca3c4016849aa4c1ac22c3803870d851dce1ba
+  data.tar.gz: d45ebbafe579ff34b4727ab14edae97898a87fd87452b841b3989f438248d927cdb16593b4ab05321bf4dce8a7f1e99f39639065798a91a7436f72f442d2b227

data/README.md

@@ -5,15 +5,15 @@
 
 ## Superpowered slots for ActionView partials
 
-Slotify adds an unobtrusive (but powerful!) **content slot API** to ActionView partials. 
+Slotify brings a ViewComponent-style **content slot API** to ActionView partials.
 
-Slots are a convenient way to pass blocks of content in to a partial without having to resort to ugly `<% capture do ... end %>` workarounds or unscoped (global) `<% content_for :foo %>` declarations.
+Slots are a convenient way to pass blocks of content in to a partial without having to resort to ugly `<% capture do ... end %>` workarounds or unscoped (global) `<% content_for :foo %>` declarations. 
 
 Slotified partials are a great way to build components in a Rails app without the additional overhead and learning curve of libraries like [ViewComponent](https://viewcomponent.org/) or [Phlex](https://www.phlex.fun/).
 
-> [!CAUTION]
-> Slotify is still in a early stage of development.
-The documentation is still quite sparse and the API could change at any point prior to a `v1.0` release.
+> [!WARNING]
+> Slotify is in an early stage of development and has not been properly battle-tested yet.
+The documentation is still a work-in-progress and the API may change between point releases until it reaches `v1.0`.
 
 ### 
 
@@ -25,13 +25,12 @@ Slotify slots are defined using a **[strict locals](https://guides.rubyonrails.o
 <%# slots: (title:, body: nil, theme: "default") -%>
 ```
 
-Slot content is accessed via **standard local variables** within the partial. So a simple, slot-enabled `article` partial template might look something like this:
+Slot content is accessed via **standard local variables** within the partial. So a simple, slot-enabled `example` partial template might look something like this:
 
 ```erb
-<!-- _article.html.erb -->
+# views/examples/_example.html.erb
 
 <%# slots: (title: "Default title", body: nil) -%>
-
 <article>
   <h1><%= title %></h1>
   <% if body.present? %>
@@ -50,7 +49,9 @@ When the partial is rendered, a special `partial` object is yielded as an argume
 For example, here our `article` partial is being rendered with content for the `title` and `body` slots that were defined above:
 
 ```erb
-<%= render "article" do |partial| %>
+# views/examples/show.html.erb
+
+<%= render "example" do |partial| %>
   <% partial.with_title "This is a title" %>
   <% partial.with_body do %>
     <p>You can use <%= tag.strong "markup" %> within slot content blocks without
@@ -68,10 +69,10 @@ But this example just scratches the surface of what Slotify slots can do. Have a
 <summary><h4>More full-featured example</h4></summary>
 
 ```erb
-<!-- views/_example.html.erb -->
+# views/examples/_example.html.erb
 
 <%# locals: (id:) -%>
-<%# slots: (title: "Example title", lists: nil, quotes: nil, website_link:) -%>
+<%# slots: (title: "Example title", lists: [], quotes: [], website_link:) -%>
 
 <%= tag.section id: do %>
   <h1 class="example-title">
@@ -95,10 +96,10 @@ But this example just scratches the surface of what Slotify slots can do. Have a
 ```
 
 ```erb
-<!-- views/_list.html.erb -->
+# views/examples/_list.html.erb
 
 <%# locals: (title:) -%>
-<%# slots: (items: nil) -%>
+<%# slots: (items: []) -%>
  
 <h3><%= title %></h3>
 
@@ -110,7 +111,7 @@ But this example just scratches the surface of what Slotify slots can do. Have a
 ```
 
 ```erb
-<!-- views/slotify.html.erb -->
+# views/examples/show.html.erb
 
 <%= render "example", id: "slotify-example" do |partial| %>
   <% partial.with_subtitle do %>
@@ -156,13 +157,13 @@ Required slots are defined without a default value.
 If no content is provided for a required slot then a `StrictSlotsError` exception will be raised.
 
 ```erb
-<!-- _required.html.erb -->
+# views/examples/_required.html.erb
 
 <%# slots: (title:) -%>
 <h1><%= title %></h1>
-```
 
-```erb
+# views/examples/show.html.erb
+
 <%= render "required" do |partial| %>  
   <!-- ❌ raises an error, no content set for the `title` slot -->
 <% end %>
@@ -177,33 +178,6 @@ the default value will be used instead.
 <%# slots: (title: "Default title", author: nil) -%>
 ```
 
-### Using alongside strict locals
-
-Strict locals can be defined in 'slotified' partial templates in the same way as usual,
-either above or below the `slots` definition.
-
-```erb
-<!-- _article.html.erb -->
-
-<%# locals: (title:) -%>
-<%# slots: (body: "No content available") -%>
-
-<article>
-  <h1><%= title %></h1>
-  <div><%= body %></div>
-</article>
-```
-
-Locals are provided when rendering the partial in the usual way.
-
-```erb
-<%= render "article", title: "Article title here" do |partial| %>
-  <% partial.with_body do %>
-    <p>Body content here...</p>
-  <% end %>
-<% end %>
-```
-
 ### Setting slot values
 
 Content is passed into slots using dynamically generated `partial#with_<slot_name>` writer methods.
@@ -215,9 +189,7 @@ The following two examples are equivalent:
 <%= render "example" do |partial| %>
   <% partial.with_title "Title passed as argument" %>
 <% end %>
-```
 
-```erb
 <%= render "example" do |partial| %>
   <% partial.with_title do %>
     Title passed as block content
@@ -242,38 +214,44 @@ The slot value writer methods also accept optional arbitrary keyword arguments.
 These can then be accessed in the partial template via the `.options` method on the slot variable.
 
 ```erb
+# views/examples/show.html.erb
+
 <%= render "example" do |partial| %>
   <% partial.with_title "The title", class: "color-hotpink", data: {controller: "fancy-title"} %>
 <% end %>
-```
 
-```erb
-<%# slots: (title:) -%>
+# views/examples/_example.html.erb
 
-<%= title.options.keys %> <!-- [:class, :data] -->
-<%= title %> <!-- The title -->
+<%# slots: (title:) -%>
+<%= title.options.keys %> ➡️ [:class, :data]
+<%= title %>              ➡️ "The title"
 ```
 
 Slot options can be useful for providing tag attributes when rendering slot content or rendering variants
 of a slot based on an option value.
 
+```erb
+<%= tag.h1 **title.options %><%= title %><% end %>
+➡️ <h1 class="color-hotpink" data-controller="fancy-title">The title</h1>
+```
+
 When rendered as a string the options are passed through the Rails `tag.attributes` helper to generate an HTML tag attributes string:
 
 ```erb
 <h1 <%= title.options %>><%= title %></h1> 
-<!-- <h1 class="color-hotpink" data-controller="fancy-title">The title</h1> -->
+➡️ <h1 class="color-hotpink" data-controller="fancy-title">The title</h1>
 ```
 
-### Slot types
+### Single- vs multi-value slots
 
 There are two types of slots.
 
-* **Single-value** slots can only be called **once** and return **a single value**.
-* **Multiple-value** slots can be called **many times** and return **an array of values**.
+* **Single-value** slots can only be called **once** when rendering the partial. The corresponding variable in the template represents a single slot value.
+* **Multi-value** slots can be called **many times** when rendering the partial. The corresponding variable in the template represents **a collection of slot values**.
 
 #### Single-value slots
 
-Single-value slots are defined using a **singlular** slot name:
+Single-value slots are defined using a **singular** slot name:
 
 ```erb
 <%# slots: (item: nil) -%>
@@ -283,15 +261,17 @@ Single-value slots can be called once (at most)
 and their corresponding template variable represents a single value:
 
 ```erb
+# views/examples/show.html.erb
+
 <%= render "example" do |partial| %>
   <% partial.with_item "Item one" %>
 <% end %>
-```
 
-```erb
+# views/examples/_example.html.erb
+
 <%# slots: (item: nil) -%>
 <div>
-  <%= item %> <!-- "Item one" -->
+  <%= item %> ➡️ "Item one"
 </div>
 ```
 
@@ -301,35 +281,37 @@ and their corresponding template variable represents a single value:
 > ```erb
 > <%= render "example" do |partial| %>
 >   <% partial.with_item "Item one" %>
->   <% partial.with_item "Item two" %> # ❌ raises an error!
+>   <% partial.with_item "Item two" %> ❌ raises an error!
 > <% end %>
 > ```
 
-#### Multiple-value slots
+#### Multi-value slots
 
-Multiple-value slots are defined using a **plural** slot name:
+Multi-value slots are defined using a **plural** slot name:
 
 ```erb
-<%# slots: (items: nil) -%>
+<%# slots: (items: []) -%>
 ```
 
-Multiple-value slots can be called as many times as needed
+Multi-value slots can be called as many times as needed
 and their corresponding template variable represents an array of values.
 
-The slot writer methods for multiple-value slots use the **singluar form** of the slot name (e.g. `#with_item` for the `items` slot).
+The slot writer methods for multi-value slots use the **singluar form** of the slot name (e.g. `#with_item` for the `items` slot).
 
 ```erb
+# views/examples/show.html.erb
+
 <%= render "example" do |partial| %>
   <% partial.with_item "Item one" %>
   <% partial.with_item "Item two" %>
   <% partial.with_item "Item three" %>
 <% end %>
-```
 
-```erb
-<%# slots: (items: nil) -%>
+# views/examples/_example.html.erb
+
+<%# slots: (items: []) -%>
 
-<%= items %> <!-- ["Item one", "Item two", "Item three"] -->
+<%= items %> ➡️ ["Item one", "Item two", "Item three"]
 
 <ul>
   <% items.each do |item| %>
@@ -338,28 +320,119 @@ The slot writer methods for multiple-value slots use the **singluar form** of th
     </li>
   <% end %>
 </ul>
+
+➡️ <ul><li>Item one</li><li>Item two</li><li>Item three</li></ul>
 ```
 
-### Using slots with helpers
+### Using with view helpers
 
-> _Docs coming soon..._ 
+Slot values can be used with Rails view helpers (such as tag helpers) in the partial templates in the usual way:
+
+```erb
+<%= tag.h1 title %>
+```
+
+[Slot options](#slot-options) can be passed to helpers alongside the content by splatting slot value `.options`:
+
+```erb
+<%= tag.h1 title, **title.options %>
+```
+
+#### Slotified helpers
+
+Slotify patches a number of the most commonly used view helpers (such as `content_tag`, `link_to`) so that slot value arguments and options are transparently expanded and passed to the underlying helper. This means that manual args/options splatting (as described above) is not required.
+
+```erb
+# views/examples/show.html.erb
+
+<%= render "example" do |partial| %>
+  <% partial.with_title "The title", class: "color-hotpink" %>
+  <% partial.with_website_link "Example website", "https://example.com", data: {controller: "clicker"} %>
+<% end %>
+
+# views/examples/_example.html.erb
+
+<%# slots: (title: nil, website_link: nil) -%>
+
+<%= content_tag :h1, title %>
+➡️ <h1 class="color-hotpink">The title</h1>
+
+<%= link_to website_link %>
+➡️ <a href="https://example.com" data-controller="clicker">Example website</a>
+```
+
+Any options provided to the helper are 'smart-merged' with slot value options using the [Phlex `mix` helper](https://www.phlex.fun/sgml/helpers#mix) to ensure token list options (such as class names) are properly combined instead of being overwritten.
 
 ```erb
-<% partial.with_title "The title", class: "color-hotpink" %>
-<% partial.with_website_link "Example website", "https://example.com", data: {controller: "external-link"} %>
+<%= content_tag :h1, title, class: "text-xl", id: "headline" %> <!-- options here are merged with slot value options -->
+➡️ <h1 class="text-xl color-hotpink" id="headline">The title</h1>
 
-<% partial.with_item "Item one" %>
-<% partial.with_item "Item two", class: "highlight" %>
+<%= link_to website_link, target: "_blank" %>
+➡️ <a href="https://example.com" data-controller="clicker" target="_blank">Example website</a>
 ```
 
+If a slotified helper is provided with a slot value collection (i.e. from a [multi-value slot](#multi-value-slots)) then the helper will be run once for each value in the collection:
+
 ```erb
-<%= content_tag :h1, title %> <!-- <h1 class="color-hotpink">The title</h1> -->
-<%= content_tag :h1, title, class: "example-title" %> <!-- <h1 class="example-title color-hotpink">The title</h1> -->
+# views/examples/show.html.erb
+
+<%= render "example" do |partial| %>
+  <% partial.with_item "Item one" %>
+  <% partial.with_item "Item two", class: "highlight" %>
+<% end %>
+
+# views/examples/_example.html.erb
+
+<%# slots: (items: []) -%>
+
+<%= content_tag :li, items %>
+➡️ <li>Item one</li><li class="highlight">Item two</li>
+
+<%= content_tag :li, items, class: "item" %>
+➡️ <li class="item">Item one</li><li class="item highlight">Item two</li>
+```
+
+#### List of 'slotified' helpers
+
+* `tag` _(top-level `tag` helper only, not the `tag.<tag_name>` shorthands)_
+* `content_tag`
+* `link_to`
+* `link_to_if`
+* `link_to_unless`
+* `link_to_unless_current`
+* `button_to`
+* `mail_to`
+* `sms_to`
+* `phone_to`
+* `url_for`
+
+### Using alongside strict locals
+
+Strict locals can be defined in 'slotified' partial templates in the same way as usual,
+either above or below the `slots` definition.
+
+```erb
+# views/examples/_example.html.erb
+
+<%# locals: (title:) -%>
+<%# slots: (body: "No content available") -%>
+
+<article>
+  <h1><%= title %></h1>
+  <div><%= body %></div>
+</article>
+```
+
+Locals are provided when rendering the partial in the usual way.
 
-<%= link_to website_link %> <!-- <a href="https://example.com" data-controller="external-link">Example website</a> -->
+```erb
+# views/examples/show.html.erb
 
-<%= content_tag :li, items %> <!-- <li>Item one</li><li class="highlight">Item two</li> -->
-<%= content_tag :li, items, class: "item" %> <!-- <li class="item">Item one</li><li class="item highlight">Item two</li> -->
+<%= render "article", title: "Article title here" do |partial| %>
+  <% partial.with_body do %>
+    <p>Body content here...</p>
+  <% end %>
+<% end %>
 ```
 
 ### Rendering slots
@@ -371,9 +444,9 @@ The slot writer methods for multiple-value slots use the **singluar form** of th
 **Singlular slot value variables** in partial templates are actually instances of `Slotity::Value`.
 These value objects are automatically stringified so in most cases you will not even be aware of this and they can just be treated as regular string variables.
 
-
-
 ```erb
+# views/examples/show.html.erb
+
 <%= render "example" do |partial| %>
   <% partial.with_title class: "color-hotpink" do %>
     The title
@@ -382,19 +455,24 @@ These value objects are automatically stringified so in most cases you will not
 ```
 
 ```erb
-<% title.is_a?(Slotify::Value) %> <!-- true -->
-<% items.is_a?(Slotify::ValueCollection) %> <!-- true -->
+# views/examples/_example.html.erb
 
-<%= title %> <!-- "The title" -->
-<% title.content %> <!-- "The title" -->
+<%# slots: (title: nil) -%>
 
-<% title.options %> <!-- { class: "color-hotpink" } (hash of any options provided when calling the `.with_title` slot value writer method) -->
-<%= title.options %> <!-- "class='color-hotpink'" (string generated by passing the options hash through the Rails `tag.attributes` helper) -->
+<% title.is_a?(Slotify::Value) %> ➡️ true
+
+<%= title %>         ➡️ "The title"
+<% title.content %>  ➡️ "The title"
+
+<% title.options %>  ➡️ { class: "color-hotpink" }
+<%= title.options %> ➡️ "class='color-hotpink'" 
 ```
 
 **Plural slot value variables** in partial templates are instances of the enumerable `Slotify::ValueCollection` class, with all items instances of `Slotity::Value`.
 
 ```erb
+# views/examples/show.html.erb
+
 <%= render "example" do |partial| %>
   <% partial.with_item "Item one" %>
   <% partial.with_item "Item two", class: "current" %>
@@ -402,14 +480,18 @@ These value objects are automatically stringified so in most cases you will not
 ```
 
 ```erb
-<% items.is_a?(Slotify::ValueCollection) %> <!-- true -->
+# views/examples/_example.html.erb
+
+<%# slots: (items: []) -%>
+
+<% items.is_a?(Slotify::ValueCollection) %> ➡️ true
 
 <% items.each do |item| %>
   <li <%= item.options %>><%= item %></li>
 <% end %>
-<!-- <li>Item one</li> <li class="current">Item two</li> -->
+➡️ <li>Item one</li> <li class="current">Item two</li>
 
-<%= items %> <!-- "Item one Item two" -->
+<%= items %> ➡️ "Item one Item two"
 ```
 
 #### `Slotity::Value`
@@ -426,15 +508,41 @@ Returns a `Slotify::ValueOptions` instance that can be treated like a `Hash`. Ca
 
 When converted to a string either explicitly (via `.to_s`) or implicitly (by outputting the value template using ERB `<%= %>` expression tags) the stringified value is generated by passing the options hash through the Rails `tag.attributes` helper.
 
+**`.args`**
+
+Returns an array of the arguments that were passed into the slot writer method (if any) when rendering the partial.
+
+Slot arguments can also be accessed using hash access notation.
+
+```erb
+# views/examples/show.html.erb
+
+<%= render "example" do |partial| %>
+  <% partial.with_link "Example link", "https://example.com", class: "external-link" %>
+<% end %>
+```
+
+```erb
+# views/examples/_example.html.erb
+
+<%# slots: (link: nil) -%>
+
+<% link.args %> ➡️ ["Example link", "https://example.com"]
+<% link[0] %>   ➡️ "Example link"
+<% link[1] %>   ➡️ "https://example.com"
+```
+
 **`.with_default_options(default_options)`**
 
-Merges the options set when calling the slot value writer method with the `default_options` hash provided and returns a new `Slotity::Value` instance with the merged options set.
+Merges slot options with the `default_options` hash provided. Returns a new `Slotity::Value` instance with the merged options set.
+
+Options are 'smart-merged' using the [Phlex `mix` helper](https://www.phlex.fun/sgml/helpers#mix) to ensure token list options (such as class names) are properly combined instead of being overwritten.
 
 ```erb
-<% title_with_default_opts = title.with_default_options(class: "size-lg", aria: {level: 1}) %> <!-- apply default options -->
+<% title_with_defaults = title.with_default_options(class: "size-lg", aria: {level: 1}) %> 
 
-<% title_with_default_opts.options %> <!-- { class: "size-lg color-hotpink", aria: {level: 1} } -->
-<%= title_with_default_opts.options %> <!-- "class='size-lg color-hotpink' aria-level='1'" -->
+<% title_with_defaults.options %>  ➡️ { class: "size-lg color-hotpink", aria: {level: 1} }
+<%= title_with_defaults.options %> ➡️ "class='size-lg color-hotpink' aria-level='1'"
 ```
 
 ## Slotify vs alternatives
@@ -447,10 +555,10 @@ However there are a number of key differences:
 * Slotify requires the explicit definition of slots using 'strict locals'-style comments;
 Nice partials slots are implicitly defined when rendering the partial.
 * Slotify slot values are available as local variables;
-with Nice partials slot values are accessed via methods on the `partial` variable.
-* Slotify has the concept (and enforces the use) of single-value vs. multiple-value slots.
+with Nice partials slot values are accessed via methods a single `partial` variable.
+* Slotify has the concept (and enforces the use) of single- vs. multi-value slots.
 * Slotify slot content and options are transparently expanded and merged into defaults when using with helpers like `content_tag` and `link_to`.
-* Slotify slot values are `renderable` objects
+* Slotify slot values are `renderable` objects.
 
 You might choose slotify if you prefer a stricter, 'Rails-native'-feeling slots implementation, and Nice Partials if you want more render-time flexibility and a clearer
 separation of 'nice partial' functionality from ActionView-provided locals etc.
@@ -458,8 +566,7 @@ separation of 'nice partial' functionality from ActionView-provided locals etc.
 #### `view_component`
 
 Both [ViewComponent](https://viewcomponent.org/) and Slotify provide a 'slots' API for content blocks.
-Slotify's slot writer syntax (i.e. `.with_<slot_name>` methods) and the concept of single-value (`renders_one`) vs multiple-value (`renders_many`) slots
-are both modelled on ViewComponent's slots implementation.
+Slotify's slot writer syntax (i.e. `.with_<slot_name>` methods) and the concept of single-value (`renders_one`) vs multi-value (`renders_many`) slots are both modelled on ViewComponent's slots implementation.
 
 However apart from that they are quite different. Slotify adds functionality to regular ActionView partials whereas ViewComponent provides a complete standalone component system.
 
@@ -484,78 +591,181 @@ And then run `bundle install`. You are good to go!
 * `Rails 7.1+`
 * `Ruby 3.1+`
 
-## Credits
+## Testing 
 
-Slotify was inspired by the excellent [nice_partials gem](https://github.com/bullet-train-co/nice_partials) as well as ViewComponent's [slots implementation](https://viewcomponent.org/guide/slots.html).
+Slotify uses MiniTest for its test suite.
 
-`nice_partials` provides very similar functionality to Slotify but takes a slightly different approach/style. So if you are not convinced by Slotify then definitely [check it out](https://github.com/bullet-train-co/nice_partials)!
+[Appraisal](https://github.com/thoughtbot/appraisal) is used in CI to test against a matrix of Ruby/Rails versions.
 
-## Benchmarks
+#### Run tests
 
-Slotify is still in the early stages of development and no attempt has yet been made to optimise rendering performance.
+```shell
+bundle exec bin/test
+```
 
-Below are some initial (crude) benchmarking comparisons with other similar gems.
+### Benchmarks
 
-> [!TIP]
-> Benchmarks can be run using the `bin/benchmarks` command from the repository root.
+Some crude render performance benchmark tests for `slotify`, `view_component` and `nice_partials` can be found in the `/performance` directory.
+
+All benchmarks use a vanilla ActionView template rendering performance measurement as the baseline for comparison against.
+
+* The **slots** benchmarks compare the performance of rendering a partial/component that uses slots against the baseline.
+* The **no slots** benchmarks compare the performance of rendering a partial/component without slots (i.e. values provided as keyword arguments) against the baseline. These results are useful for determining how much the gem being benchmarked affects rendering performance even when slots are not used.
+
+The benchmark tests are a work in progress right now so any suggestions for improvements would be much appreciated!
+
+#### Benchmark results summary
+
+* `slotify`, `nice_partials` and `view_component` all result in slighly slower partial/component rendering speeds compared to the 'vanilla ActionView' baseline (as expected).
+* `slotify` is currently the closest to the baseline when rendering partials/components without any slots (~1.2x slower).
+* `slotify` is currently the furthest from the baseline when rendering partials/components using slots (~3x slower).
+
+
+#### Running benchmarks
+
+You can run the benchmark tests locally using the `bin/benchmark` command from the root of the repository.
+
+```shell
+bundle exec bin/benchmarks # run all benchmarks
+bundle exec bin/benchmarks slotify # run specified benchmarks only (slotify / view_component / nice_partials)
+bundle exec bin/benchmarks --no-slots # run 'no-slots' benchmarks
+```
+
+<details>
+<summary><h4>Recent benchmark results</h4></summary>
+
+#### With slots:
 
 ```
-✨🦄 ACTION_VIEW 🦄✨
+➜ bin/benchmark
+
+🏁🏁 SLOTIFY 🏁🏁
+
+ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
+Warming up --------------------------------------
+            baseline    11.836k i/100ms
+Calculating -------------------------------------
+            baseline    118.334k (± 2.8%) i/s    (8.45 μs/i) -    591.800k in   5.005403s
 
 ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
 Warming up --------------------------------------
-            no slots    12.997k i/100ms
-               slots    10.891k i/100ms
+               slots     2.229k i/100ms
 Calculating -------------------------------------
-            no slots    125.622k (± 5.4%) i/s    (7.96 μs/i) -      1.261M in  10.072521s
-               slots    108.468k (± 3.3%) i/s    (9.22 μs/i) -      1.089M in  10.053026s
+               slots     26.066k (± 7.8%) i/s   (38.36 μs/i) -    131.511k in   5.087467s
 
 Comparison:
-            no slots:   125621.9 i/s
-               slots:   108467.5 i/s - 1.16x  slower
+            baseline:   118333.8 i/s
+               slots:    26066.0 i/s - 4.54x  slower
 
 
-✨🦄 NICE_PARTIALS 🦄✨
+🏁🏁 NICE_PARTIALS 🏁🏁
 
 ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
 Warming up --------------------------------------
-            no slots    11.822k i/100ms
-               slots     4.204k i/100ms
+            baseline    12.072k i/100ms
 Calculating -------------------------------------
-            no slots    114.190k (± 4.7%) i/s    (8.76 μs/i) -      1.147M in  10.069870s
-               slots     41.138k (± 4.3%) i/s   (24.31 μs/i) -    411.992k in  10.039730s
+            baseline    114.740k (± 4.4%) i/s    (8.72 μs/i) -    579.456k in   5.060487s
+
+ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
+Warming up --------------------------------------
+               slots     3.626k i/100ms
+Calculating -------------------------------------
+               slots     35.971k (± 6.1%) i/s   (27.80 μs/i) -    181.300k in   5.061126s
 
 Comparison:
-            no slots:   114190.2 i/s
-               slots:    41137.9 i/s - 2.78x  slower
+            baseline:   114740.4 i/s
+               slots:    35971.0 i/s - 3.19x  slower
 
 
-✨🦄 VIEW_COMPONENT 🦄✨
+🏁🏁 VIEW_COMPONENT 🏁🏁
 
 ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
 Warming up --------------------------------------
-            no slots    20.329k i/100ms
-               slots     7.409k i/100ms
+            baseline    11.991k i/100ms
 Calculating -------------------------------------
-            no slots    196.288k (± 4.7%) i/s    (5.09 μs/i) -      1.972M in  10.073103s
-               slots     71.311k (± 5.0%) i/s   (14.02 μs/i) -    718.673k in  10.108426s
+            baseline    118.532k (± 2.3%) i/s    (8.44 μs/i) -    599.550k in   5.060901s
+
+ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
+Warming up --------------------------------------
+               slots     7.493k i/100ms
+Calculating -------------------------------------
+               slots     72.281k (± 6.3%) i/s   (13.83 μs/i) -    359.664k in   5.002508s
 
 Comparison:
-            no slots:   196287.6 i/s
-               slots:    71310.5 i/s - 2.75x  slower
+            baseline:   118532.2 i/s
+               slots:    72281.3 i/s - 1.64x  slower
+```
+
+#### Without slots:
+
+```
+➜ bin/benchmark --no-slots
 
+🏁🏁 SLOTIFY 🏁🏁
 
-✨🦄 SLOTIFY 🦄✨
+ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
+Warming up --------------------------------------
+            baseline    13.071k i/100ms
+Calculating -------------------------------------
+            baseline    127.673k (± 3.6%) i/s    (7.83 μs/i) -    640.479k in   5.023506s
 
 ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
 Warming up --------------------------------------
-            no slots    10.883k i/100ms
-               slots    77.000 i/100ms
+            no slots    11.029k i/100ms
 Calculating -------------------------------------
-            no slots    110.153k (± 4.8%) i/s    (9.08 μs/i) -      1.099M in  10.009002s
-               slots    789.118 (± 4.1%) i/s    (1.27 ms/i) -      7.931k in  10.071749s
+            no slots    110.253k (± 2.0%) i/s    (9.07 μs/i) -    551.450k in   5.003625s
 
 Comparison:
-            no slots:   110152.8 i/s
-               slots:      789.1 i/s - 139.59x  slower
+            baseline:   127673.0 i/s
+            no slots:   110252.6 i/s - 1.16x  slower
+
+
+🏁🏁 NICE_PARTIALS 🏁🏁
+
+ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
+Warming up --------------------------------------
+            baseline    13.016k i/100ms
+Calculating -------------------------------------
+            baseline    131.103k (± 1.8%) i/s    (7.63 μs/i) -    663.816k in   5.065054s
+
+ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
+Warming up --------------------------------------
+            no slots     4.556k i/100ms
+Calculating -------------------------------------
+            no slots     44.888k (± 3.7%) i/s   (22.28 μs/i) -    227.800k in   5.082635s
+
+Comparison:
+            baseline:   131103.4 i/s
+            no slots:    44888.2 i/s - 2.92x  slower
+
+
+🏁🏁 VIEW_COMPONENT 🏁🏁
+
+ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
+Warming up --------------------------------------
+            baseline    13.454k i/100ms
+Calculating -------------------------------------
+            baseline    128.817k (± 5.7%) i/s    (7.76 μs/i) -    645.792k in   5.038036s
+
+ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
+Warming up --------------------------------------
+            no slots    17.335k i/100ms
+Calculating -------------------------------------
+            no slots    203.191k (± 2.2%) i/s    (4.92 μs/i) -      1.023M in   5.036040s
+
+Comparison:
+            no slots:   203190.7 i/s
+            baseline:   128817.3 i/s - 1.58x  slower
 ```
+
+</details>
+
+## Credits
+
+Slotify was inspired by the excellent [nice_partials gem](https://github.com/bullet-train-co/nice_partials) as well as ViewComponent's [slots implementation](https://viewcomponent.org/guide/slots.html).
+
+`nice_partials` provides very similar functionality to Slotify but takes a slightly different approach/style. So if you are not convinced by Slotify then definitely [check it out](https://github.com/bullet-train-co/nice_partials)!
+
+## License
+
+The `slotify` gem is available as open source under the terms of the MIT License.

data/lib/slotify/concerns/symbol_inflection_helper.rb

@@ -0,0 +1,19 @@
+module Slotify
+  module SymbolInflectionHelper
+    extend ActiveSupport::Concern
+
+    mattr_accessor :singularizations, default: {}
+
+    def singular?(sym)
+      singularize(sym.to_sym) == sym.to_sym
+    end
+
+    def plural?(sym)
+      !singular?(sym)
+    end
+
+    def singularize(sym)
+      singularizations[sym.to_sym] ||= sym.to_s.singularize.to_sym
+    end
+  end
+end

data/lib/slotify/error.rb

@@ -2,18 +2,9 @@ module Slotify
   class UnknownSlotError < NameError
   end
 
-  class SlotsDefinedError < RuntimeError
-  end
-
-  class UndefinedSlotError < StandardError
-  end
-
   class MultipleSlotEntriesError < ArgumentError
   end
 
-  class SlotArgumentError < ArgumentError
-  end
-
   class StrictSlotsError < ArgumentError
   end
 

data/lib/slotify/extensions/base.rb

@@ -3,20 +3,13 @@ module Slotify
     module Base
       include SlotCompatability
 
-      attr_accessor :partial
+      attr_accessor :slotify
 
-      def render(options = {}, locals = {}, &block)
-        @partial = Slotify::Partial.new(self)
-        super
+      def capture_with_outer_slotify_access(*args, &block)
+        inner_slotify, @slotify = slotify, slotify.outer_slotify
+        inner_slotify.capture(*args, &block)
       ensure
-        @partial = partial.outer_partial
-      end
-
-      def capture_with_outer_partial_access(*args, &block)
-        inner_partial, @partial = partial, partial.outer_partial
-        inner_partial.capture(*args, &block)
-      ensure
-        @partial = inner_partial
+        @slotify = inner_slotify
       end
 
       make_compatible_with_slots :url_for, :link_to, :button_to, :link_to_unless_current,

data/lib/slotify/extensions/partial_renderer.rb

@@ -4,17 +4,20 @@ module Slotify
       def render_partial_template(view, locals, template, layout, block)
         return super unless template.strict_slots?
 
-        view.partial.define_slots!(template.strict_slots_keys)
+        view.slotify = Slotify::Slots.new(view, template.strict_slots_keys)
 
-        view.capture_with_outer_partial_access(&block) if block
-        locals = locals.merge(view.partial.slot_locals)
+        view.capture_with_outer_slotify_access(&block) if block
+
+        locals = locals.merge(view.slotify.slot_locals)
 
         decorate_strict_slots_errors do
           super(view, locals, template, layout, block)
         end
+      ensure
+        view.slotify = view.slotify.outer_slotify if view.slotify
       end
 
-      def decorate_strict_slots_errors(&block)
+      def decorate_strict_slots_errors
         yield
       rescue ActionView::Template::Error => error
         if missing_strict_locals_error?(error)
@@ -31,7 +34,7 @@ module Slotify
       end
 
       def missing_strict_locals_error?(error)
-        error.template && (defined?(ActionView::StrictLocalsError) && error.cause.is_a?(ActionView::StrictLocalsError)) ||
+        error.template && defined?(ActionView::StrictLocalsError) && error.cause.is_a?(ActionView::StrictLocalsError) ||
           (error.cause.is_a?(ArgumentError) && error.cause.message.match(/missing local/))
       end
     end

data/lib/slotify/extensions/template.rb

@@ -31,7 +31,7 @@ module Slotify
       end
 
       def strict_slots_keys
-        @strict_slots_keys ||= strict_slots!.scan(STRICT_SLOTS_KEYS_REGEX).map(&:first)
+        @strict_slots_keys ||= strict_slots!.scan(STRICT_SLOTS_KEYS_REGEX).map(&:first).freeze
       end
 
       def strict_locals!
@@ -44,7 +44,7 @@ module Slotify
         return super unless strict_slots?
 
         strict_slots_keys.each_with_object(+super) do |key, code|
-          code << "partial.set_slot_default(:#{key}, binding.local_variable_get(:#{key})); #{key} = partial.public_send(:#{key});"
+          code << "slotify.set_slot_default(:#{key}, binding.local_variable_get(:#{key})); #{key} = slotify.content_for(:#{key});"
         end
       end
     end

data/lib/slotify/services/tag_options_merger.rb

@@ -1,53 +1,46 @@
 module Slotify
   module TagOptionsMerger
     class << self
-      include ::ActionView::Helpers::TagHelper
-
       def call(original, target)
-        original = original.to_h.deep_symbolize_keys
-        target = target.to_h.deep_symbolize_keys
-
-        target.each do |key, value|
-          original[key] = case key
-          when :data
-            merge_data_options(original[key], value)
-          when :class
-            merge_class_options(original[key], value)
-          else
-            value
-          end
-        end
-
-        original
+        mix(original, target)
       end
 
       private
 
-      def merge_data_options(original_data, target_data)
-        original_data = original_data.dup
+      # https://www.phlex.fun/sgml/helpers#mix
+      def mix(*args)
+        args.each_with_object({}) do |object, result|
+          result.merge!(object) do |_key, old, new|
+            case [old, new].freeze
+            in [Array, Array] | [Set, Set]
+              old + new
+            in [Array, Set]
+              old + new.to_a
+            in [Array, String]
+              old + [new]
+            in [Hash, Hash]
+              mix(old, new)
+            in [Set, Array]
+              old.to_a + new
+            in [Set, String]
+              old.to_a + [new]
+            in [String, Array]
+              [old] + new
+            in [String, Set]
+              [old] + new.to_a
+            in [String, String]
+              "#{old} #{new}"
+            in [_, nil]
+              old
+            else
+              new
+            end
+          end
 
-        target_data.each do |key, value|
-          values = [original_data[key], value]
-          original_data[key] = if key.in?([:controller, :action]) && all_kind_of?(String, values)
-            merge_strings(values)
-          else
-            value
+          result.transform_keys! do |key|
+            key.end_with?("!") ? key.name.chop.to_sym : key
           end
         end
-
-        original_data
-      end
-
-      def merge_class_options(original_classes, target_classes)
-        class_names(original_classes, target_classes)
-      end
-
-      def merge_strings(*args)
-        args.map(&:presence).compact.join(" ")
-      end
-
-      def all_kind_of?(kind, values)
-        values.none? { !_1.is_a?(kind) }
       end
     end
   end

data/lib/slotify/{partial.rb → slots.rb}

@@ -1,19 +1,21 @@
 module Slotify
-  class Partial
-    include InflectionHelper
+  class Slots
+    include SymbolInflectionHelper
 
     RESERVED_SLOT_NAMES = [
       :content, :slot, :value, :content_for,
       :capture, :yield, :partial
     ]
 
-    attr_reader :outer_partial
+    attr_reader :outer_slotify
 
-    def initialize(view_context)
+    def initialize(view_context, slots = [])
       @view_context = view_context
-      @outer_partial = view_context.partial
+      @outer_slotify = view_context.slotify
       @values = ValueStore.new(@view_context)
       @defined_slots = nil
+
+      define_slots!(slots)
     end
 
     def content_for(slot_name)
@@ -50,8 +52,6 @@ module Slotify
     end
 
     def slot_locals
-      validate_slots!
-
       pairs = @defined_slots.map do |slot_name|
         slot_values = values.for(slot_name)
         slot_values = singular?(slot_name) ? slot_values&.first : slot_values
@@ -65,50 +65,56 @@ module Slotify
       end.to_h
     end
 
-    def define_slots!(slot_names)
-      raise SlotsDefinedError, "Slots cannot be redefined" unless @defined_slots.nil?
+    private
 
+    attr_reader :values
+
+    def slot?(slot_name)
+      slot_name && @defined_slots.include?(slot_name.to_sym)
+    end
+
+    def define_slots!(slot_names)
       @defined_slots = slot_names.map(&:to_sym).each do |slot_name|
         if RESERVED_SLOT_NAMES.include?(singularize(slot_name))
-          raise ReservedSlotNameError, ":#{slot_name} is a reserved word and cannot be used as a slot name"
+          raise ReservedSlotNameError,
+            ":#{slot_name} is a reserved word and cannot be used as a slot name"
         end
-      end
-    end
 
-    def respond_to_missing?(name, include_private = false)
-      name.start_with?("with_") || slot?(name)
-    end
-
-    def method_missing(name, *args, **options, &block)
-      if name.start_with?("with_")
-        values.add(name.to_s.delete_prefix("with_"), args, options, block)
-      elsif slot?(name)
-        content_for(name)
-      else
-        super
+        if singular?(slot_name)
+          define_single_value_slot_method(slot_name)
+        else
+          define_multi_value_slot_methods(slot_name)
+        end
       end
     end
 
-    private
+    def define_single_value_slot_method(slot_name)
+      method_name = :"with_#{slot_name}"
 
-    attr_reader :values
+      return if respond_to?(method_name)
 
-    def slot?(slot_name)
-      slot_name && @defined_slots.include?(slot_name.to_sym)
+      self.class.define_method(method_name) do |*args, **options, &block|
+        if values.for(slot_name).any?
+          raise MultipleSlotEntriesError,
+            "slot :#{slot_name} is defined as a single-value slot but was called multiple times"
+        end
+
+        values.add(slot_name, args, options, block)
+      end
     end
 
-    def validate_slots!
-      return if @defined_slots.nil?
+    def define_multi_value_slot_methods(slot_name)
+      method_name = :"with_#{slot_name}"
+      singular_slot_name = singularize(slot_name)
+
+      return if respond_to?(method_name)
 
-      undefined_slots = values.slot_names - @defined_slots.map { singularize(_1) }
-      if undefined_slots.any?
-        raise UndefinedSlotError,
-          "missing slot #{"definition".pluralize(undefined_slots.size)} for `#{undefined_slots.map { ":#{_1}(s)" }.join(", ")}`"
+      self.class.define_method(method_name) do |*args, **options, &block|
+        values.add(slot_name, args, options, block)
       end
 
-      @defined_slots.filter { singular?(_1) }.each do |slot_name|
-        slot_values = values.for(slot_name)
-        raise MultipleSlotEntriesError, "slot :#{slot_name} called #{slot_values.size} times (expected 1)" if slot_values.many?
+      self.class.define_method(:"with_#{singular_slot_name}") do |*args, **options, &block|
+        values.add(singular_slot_name, args, options, block)
       end
     end
   end

data/lib/slotify/value.rb

@@ -1,6 +1,6 @@
 module Slotify
   class Value
-    include InflectionHelper
+    include SymbolInflectionHelper
 
     attr_reader :slot_name, :args, :block
 
@@ -47,7 +47,7 @@ module Slotify
     alias_method :to_hash, :to_h
 
     def with_partial_path(partial_path)
-      Value.new(@view_context, @args, options, @block, slot_name: @slot_name, partial_path:)
+      Value.new(@view_context, @args, @options, @block, slot_name: @slot_name, partial_path:)
     end
 
     def with_default_options(default_options)
@@ -61,7 +61,7 @@ module Slotify
 
     def method_missing(name, ...)
       if name.start_with?("to_")
-        @args.first.public_send(name, ...)
+        content.public_send(name, ...)
       else
         super
       end
@@ -72,7 +72,7 @@ module Slotify
     end
 
     def render_in(view_context, &block)
-      view_context.render partial_path, **@options.to_h, &@block || block
+      view_context.render partial_path, **@options.to_h, &block || @block
     end
 
     private

data/lib/slotify/value_store.rb

@@ -1,6 +1,6 @@
 module Slotify
   class ValueStore
-    include InflectionHelper
+    include SymbolInflectionHelper
 
     def initialize(view_context)
       @view_context = view_context
@@ -13,11 +13,9 @@ module Slotify
 
     def add(slot_name, args = [], options = {}, block = nil)
       if plural?(slot_name)
-        Array.wrap(args.first).map { add(singularize(slot_name), _1, options, block) }
+        Array.wrap(args.shift).map { add(singularize(slot_name), [_1, *args], options, block) }
       else
-        MethodArgsResolver.call(args, options, block) do
-          @values << Value.new(@view_context, _1, _2, _3, slot_name: singularize(slot_name))
-        end
+        @values << Value.new(@view_context, args, options, block, slot_name: singularize(slot_name))
       end
     end
 

data/lib/slotify/version.rb

@@ -1,3 +1,3 @@
 module Slotify
-  VERSION = "0.0.4"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slotify
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - Mark Perkins
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-14 00:00:00.000000000 Z
+date: 2025-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -46,15 +46,15 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/slotify.rb
-- lib/slotify/concerns/inflection_helper.rb
 - lib/slotify/concerns/slot_compatability.rb
+- lib/slotify/concerns/symbol_inflection_helper.rb
 - lib/slotify/error.rb
 - lib/slotify/extensions/base.rb
 - lib/slotify/extensions/partial_renderer.rb
 - lib/slotify/extensions/template.rb
-- lib/slotify/partial.rb
 - lib/slotify/services/method_args_resolver.rb
 - lib/slotify/services/tag_options_merger.rb
+- lib/slotify/slots.rb
 - lib/slotify/value.rb
 - lib/slotify/value_collection.rb
 - lib/slotify/value_options.rb
@@ -79,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.5.10
 signing_key:
 specification_version: 4
 summary: Superpowered slots for your Rails partials.

data/lib/slotify/concerns/inflection_helper.rb

@@ -1,18 +0,0 @@
-module Slotify
-  module InflectionHelper
-    extend ActiveSupport::Concern
-
-    def singular?(str)
-      str = str.to_s
-      str.singularize == str && str.pluralize != str
-    end
-
-    def singularize(sym)
-      sym.to_s.singularize.to_sym
-    end
-
-    def plural?(str)
-      !singular?(str)
-    end
-  end
-end