slotify 0.0.5 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 311b3b7001fb194c8518283b714ed8f5ed5990dc5b7fa51af34a25348f00d8cd
-  data.tar.gz: d22c0b5cea41b792e837f387b6c444013ff64013b84bcf781aa67f46e91a9e6c
+  metadata.gz: 1ab98a9cc284edb88505a7e87f06b10f57d33e9e531387b3bf2eb184c2f543f5
+  data.tar.gz: 96635ec015c16ebca358ad031b8f8bf5e4c3c253102f94d8730cb894a252d3f5
 SHA512:
-  metadata.gz: 8cb049942e918fb670d775d9e7e6fe42a4db1b799d6df34a4ed7ea6dbb6f325824d52a56f629d379597e8273b3c02d6151749e6de01d7019def944b627bbc828
-  data.tar.gz: 70658ea93b6b19b14a0a608e6d3afc9e815a9f3c70fdfdd7a9d5ec20a9743b4fcb3603e6c2973381e7219cf4b39dd65e42448be5874446780a8c020055923061
+  metadata.gz: df1dee1e6d19c450efdbfe4cffac050b7d4f13dd76d25ebbfcbfb2ddc187373e4c597fd1902c8e006077167a6f2919eee7e00d064dee75556d20ee0929886d1c
+  data.tar.gz: e05a1dc621cb9bdc7b8e0c269bfd472cb7790edc2d94a8c8f9aee7f714b0a3ff52cfa714cc2c041afdc2cfa33245b0faf036172c3b742399bc19e8df339164f6

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,36 +178,9 @@ 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>
-```
+### Passing content to slots
 
-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.
+Content is passed to slots by calling the appropriate `.with_<slot_name>` writer method on the argument yielded to the block when rendering the partial.
 
 Content can be provided as either the **first argument** or **as a block** when calling these methods at render time.
 The following two examples are equivalent:
@@ -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,34 +214,40 @@ 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**.
-* **Multi-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
 
@@ -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,7 +281,7 @@ 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 %>
 > ```
 
@@ -310,7 +290,7 @@ and their corresponding template variable represents a single value:
 Multi-value slots are defined using a **plural** slot name:
 
 ```erb
-<%# slots: (items: nil) -%>
+<%# slots: (items: []) -%>
 ```
 
 Multi-value slots can be called as many times as needed
@@ -319,17 +299,19 @@ and their corresponding template variable represents an array of values.
 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
 
-<%= items %> <!-- ["Item one", "Item two", "Item three"] -->
+<%# slots: (items: []) -%>
+
+<%= items %> ➡️ ["Item one", "Item two", "Item three"]
 
 <ul>
   <% items.each do |item| %>
@@ -338,28 +320,119 @@ The slot writer methods for multi-value slots use the **singluar form** of the s
     </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
@@ -372,6 +445,8 @@ The slot writer methods for multi-value slots use the **singluar form** of the s
 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
@@ -380,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
+
+<%# slots: (title: nil) -%>
 
-<%= title %> <!-- "The title" -->
-<% title.content %> <!-- "The title" -->
+<% title.is_a?(Slotify::Value) %> ➡️ true
 
-<% 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 %>         ➡️ "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" %>
@@ -400,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`
@@ -424,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
@@ -445,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.
+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.
@@ -456,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 multi-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.
 
@@ -491,84 +600,162 @@ Slotify uses MiniTest for its test suite.
 #### Run tests
 
 ```shell
-bin/test
+bundle exec bin/test
 ```
 
 ### Benchmarks
 
-Rendering performance benchmark tests for Slotify and a few alternatives (`action_view`, `view_component` & `nice_partials`) can be found in the `/performance` directory.
+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).
 
-These benchmarks are a little crude right now!
 
-**Run benchmarks:**
+#### Running benchmarks
+
+You can run the benchmark tests locally using the `bin/benchmark` command from the root of the repository.
 
 ```shell
-bin/benchmarks # run all benchmarks
-bin/benchmarks slotify # run Slotify benchmarks only
+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>Recent benchmark results</summary>
+<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 --------------------------------------
-            no slots    13.120k i/100ms
-               slots    11.038k i/100ms
+            baseline    11.836k i/100ms
 Calculating -------------------------------------
-            no slots    127.047k (± 5.2%) i/s    (7.87 μs/i) -      1.273M in  10.051203s
-               slots    106.400k (± 5.0%) i/s    (9.40 μs/i) -      1.071M in  10.095061s
+            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 --------------------------------------
+               slots     2.229k i/100ms
+Calculating -------------------------------------
+               slots     26.066k (± 7.8%) i/s   (38.36 μs/i) -    131.511k in   5.087467s
 
 Comparison:
-            no slots:   127047.3 i/s
-               slots:   106400.3 i/s - 1.19x  slower
+            baseline:   118333.8 i/s
+               slots:    26066.0 i/s - 4.54x  slower
 
 
 🏁🏁 NICE_PARTIALS 🏁🏁
 
 ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
 Warming up --------------------------------------
-            no slots    11.451k i/100ms
-               slots     3.889k i/100ms
+            baseline    12.072k i/100ms
+Calculating -------------------------------------
+            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 -------------------------------------
-            no slots    117.258k (± 3.3%) i/s    (8.53 μs/i) -      1.179M in  10.070693s
-               slots     40.737k (± 4.5%) i/s   (24.55 μs/i) -    408.345k in  10.051584s
+               slots     35.971k (± 6.1%) i/s   (27.80 μs/i) -    181.300k in   5.061126s
 
 Comparison:
-            no slots:   117257.7 i/s
-               slots:    40736.8 i/s - 2.88x  slower
+            baseline:   114740.4 i/s
+               slots:    35971.0 i/s - 3.19x  slower
 
 
 🏁🏁 VIEW_COMPONENT 🏁🏁
 
 ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
 Warming up --------------------------------------
-            no slots    20.270k i/100ms
-               slots     7.445k i/100ms
+            baseline    11.991k i/100ms
+Calculating -------------------------------------
+            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 -------------------------------------
-            no slots    211.571k (± 2.6%) i/s    (4.73 μs/i) -      2.128M in  10.067334s
-               slots     72.508k (± 5.2%) i/s   (13.79 μs/i) -    729.610k in  10.096809s
+               slots     72.281k (± 6.3%) i/s   (13.83 μs/i) -    359.664k in   5.002508s
 
 Comparison:
-            no slots:   211570.7 i/s
-               slots:    72508.0 i/s - 2.92x  slower
+            baseline:   118532.2 i/s
+               slots:    72281.3 i/s - 1.64x  slower
+```
 
+#### Without slots:
+
+```
+➜ bin/benchmark --no-slots
 
 🏁🏁 SLOTIFY 🏁🏁
 
 ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
 Warming up --------------------------------------
-            no slots    12.051k i/100ms
-               slots     2.710k i/100ms
+            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    11.029k i/100ms
+Calculating -------------------------------------
+            no slots    110.253k (± 2.0%) i/s    (9.07 μs/i) -    551.450k in   5.003625s
+
+Comparison:
+            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    116.156k (± 5.4%) i/s    (8.61 μs/i) -      1.169M in  10.102387s
-               slots     26.454k (± 5.4%) i/s   (37.80 μs/i) -    265.580k in  10.077285s
+            no slots     44.888k (± 3.7%) i/s   (22.28 μs/i) -    227.800k in   5.082635s
 
 Comparison:
-            no slots:   116155.7 i/s
-               slots:    26454.0 i/s - 4.39x  slower
+            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>
@@ -577,4 +764,8 @@ Comparison:
 
 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)!
+`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/error.rb

@@ -1,19 +1,13 @@
 module Slotify
-  class UnknownSlotError < NameError
-  end
-
-  class SlotsDefinedError < RuntimeError
+  class Error < StandardError
   end
 
-  class UndefinedSlotError < StandardError
+  class UnknownSlotError < NameError
   end
 
   class MultipleSlotEntriesError < ArgumentError
   end
 
-  class SlotArgumentError < ArgumentError
-  end
-
   class StrictSlotsError < ArgumentError
   end
 

data/lib/slotify/extensions/base.rb

@@ -3,13 +3,13 @@ module Slotify
     module Base
       include SlotCompatability
 
-      attr_accessor :partial
+      attr_accessor :slotify
 
-      def capture_with_outer_partial_access(*args, &block)
-        inner_partial, @partial = partial, partial.outer_partial
-        inner_partial.capture(*args, &block)
+      def capture_with_outer_slotify_access(*args, &block)
+        inner_slotify, @slotify = slotify, slotify.outer_slotify
+        inner_slotify.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,17 @@ module Slotify
       def render_partial_template(view, locals, template, layout, block)
         return super unless template.strict_slots?
 
-        view.partial = Slotify::Partial.new(view, template.strict_slots_keys)
+        view.slotify = Slotify::Slots.new(view, template.strict_slots_keys)
 
-        view.capture_with_outer_partial_access(&block) if block
+        view.capture_with_outer_slotify_access(&block) if block
 
-        locals = locals.merge(view.partial.slot_locals)
+        locals = locals.merge(view.slotify.slot_locals)
 
         decorate_strict_slots_errors do
           super(view, locals, template, layout, block)
         end
       ensure
-        view.partial = view.partial.outer_partial if view.partial
+        view.slotify = view.slotify.outer_slotify if view.slotify
       end
 
       def decorate_strict_slots_errors
@@ -34,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

@@ -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.content_for(:#{key});"
+          code << "slotify.set_slot_default(:#{key}, binding.local_variable_get(:#{key})); #{key} = slotify.content_for(:#{key});"
         end
       end
     end

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

@@ -1,5 +1,5 @@
 module Slotify
-  class Partial
+  class Slots
     include SymbolInflectionHelper
 
     RESERVED_SLOT_NAMES = [
@@ -7,11 +7,11 @@ module Slotify
       :capture, :yield, :partial
     ]
 
-    attr_reader :outer_partial
+    attr_reader :outer_slotify
 
     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
 

data/lib/slotify/version.rb

@@ -1,3 +1,3 @@
 module Slotify
-  VERSION = "0.0.5"
+  VERSION = "0.1.1"
 end

data/lib/slotify.rb

@@ -6,6 +6,7 @@ require_relative "slotify/error"
 loader = Zeitwerk::Loader.for_gem
 loader.tag = "slotify"
 loader.push_dir("#{__dir__}/slotify", namespace: Slotify)
+loader.ignore("#{__dir__}/slotify/error")
 loader.collapse("#{__dir__}/slotify/concerns")
 loader.collapse("#{__dir__}/slotify/services")
 loader.enable_reloading if ENV["RAILS_ENV"] == "development"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slotify
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.1
 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
@@ -52,9 +52,9 @@ files:
 - 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.5.10
+rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
 summary: Superpowered slots for your Rails partials.